Scraping Connectware Metrics with Self-Managed Prometheus

Verify that a Connectware metrics endpoint responds and configure a self-managed Prometheus instance to scrape it, without relying on the Prometheus Operator ServiceMonitor resource.

Configure a self-managed Prometheus instance to scrape Connectware metrics endpoints using static targets or Kubernetes Service Discovery, without relying on Prometheus Operator.

For Kubernetes deployments with Prometheus Operator, use ServiceMonitor resources through the Helm chart instead. See Configuring Prometheus Metrics.

Prerequisites

• Metrics are enabled for the component you want to scrape. See Enabling Metrics for a Single Component.

• kubectl is installed and configured for your cluster.

• You know the namespace of your Connectware installation. See Obtaining the Name, Namespace, and Version of Your Installation.

Metrics Endpoints

Each component with metrics.enabled set to true creates a dedicated Kubernetes Service for its metrics endpoint, separate from its main Service. The Service name always follows the pattern <app-name>-metrics, regardless of your installation name or namespace. All endpoints use HTTP and the path /metrics.

Component	App Name	Metrics Service	Port
Auth Server	auth-server	auth-server-metrics	9184
Broker	broker	broker-metrics	8888
NATS	nats	nats-metrics	7777
Protocol Mapper	protocol-mapper	protocol-mapper-metrics	9184
Resource Status Tracking	resource-status-tracking	resource-status-tracking-metrics	9184
Service Manager	service-manager	service-manager-metrics	9184

Scraping horizontally scaled Workloads

Workloads which are horizontally scaled, like Broker, NATS, or auth-server deliver metrics per node. Each replica exposes its own metrics endpoint and the cluster does not aggregate them. The Kubernetes Service load-balances across nodes, so scraping it by its Service name or ClusterIP returns metrics from only one node per scrape. To capture every node, scrape the individual pod endpoints, for example by using the endpoints role instead of the service role in kubernetes_sd_configs.

For node-level broker metrics and calculating cluster-level aggregates at query time, see Monitoring & Analytics.

Verifying an Endpoint with curl

To confirm that a metrics endpoint responds before configuring Prometheus:

1. Forward the component's metrics Service to your local machine. The following example targets Protocol Mapper:

kubectl port-forward -n ${NAMESPACE} svc/protocol-mapper-metrics 9184:9184

Replace protocol-mapper-metrics and 9184 with the Service name and port for your component from Metrics Endpoints. Leave this command running in its own terminal.

1. In a separate terminal, request the endpoint:

curl http://localhost:9184/metrics

The endpoint returns metrics in the OpenMetrics text format, which Prometheus scrapes natively. The following shows a sample from Protocol Mapper:

# HELP agent_connections_deployed Current number of deployed connections by protocol and status
# TYPE agent_connections_deployed gauge
agent_connections_deployed{protocol="opcua",status="connected"} 3
agent_connections_deployed{protocol="mqtt",status="connected"} 1

# HELP agent_endpoints_messages_total Total number of messages processed by endpoints
# TYPE agent_endpoints_messages_total counter
agent_endpoints_messages_total{protocol="opcua",operation="subscribe"} 42180
agent_endpoints_messages_total{protocol="mqtt",operation="write"} 14

# HELP agent_health Health status of the agent components
# TYPE agent_health gauge
agent_health{component="control-plane"} 1
agent_health{component="data-plane"} 1

Configuring Prometheus

Add a scrape job to your prometheus.yml file. Choose one of the following approaches.

Static Targets

Use a static target when you know the exact Service address you want to scrape. The following example targets Protocol Mapper:

prometheus.yml

scrape_configs:
  - job_name: connectware-protocol-mapper
    static_configs:
      - targets:
          - protocol-mapper-metrics.${NAMESPACE}.svc.cluster.local:9184

Add one job per component, replacing the Service name and port from Metrics Endpoints. This approach requires updating prometheus.yml whenever you change a component's metrics configuration.

Kubernetes Service Discovery

Every metrics Service carries prometheus.io/scrape, prometheus.io/port, and prometheus.io/path annotations once metrics.enabled is true. If your Prometheus instance discovers targets through kubernetes_sd_configs, configure a scrape job that filters on these annotations:

prometheus.yml

scrape_configs:
  - job_name: connectware
    kubernetes_sd_configs:
      - role: service
    relabel_configs:
      - source_labels: [__meta_kubernetes_service_annotation_prometheus_io_scrape]
        action: keep
        regex: true
      - source_labels:
          - __address__
          - __meta_kubernetes_service_annotation_prometheus_io_port
        action: replace
        regex: ([^:]+)(?::\d+)?;(\d+)
        replacement: $1:$2
        target_label: __address__
      - source_labels: [__meta_kubernetes_service_annotation_prometheus_io_path]
        action: replace
        regex: (.+)
        target_label: __metrics_path__

This job automatically picks up every Connectware metrics Service in the cluster without requiring a ServiceMonitor.

For the full relabeling syntax, see the Prometheus documentation on kubernetes_sd_config.

Avoiding the Scrape Rate Limit

Auth Server, Protocol Mapper, Resource Status Tracking, and Service Manager limit how many scrape requests their metrics endpoint accepts within a time window. If you set a short scrape interval or scrape a component from multiple Prometheus jobs simultaneously, you may exceed rateLimit.count. Increase rateLimit.count or rateLimit.windowMs for the affected component, or reduce your scrape frequency. See Configuring Prometheus Metrics for the full Helm values reference.

Broker and NATS do not have a configurable rate limit.