> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-6-0/cybus-helm-charts/working-with-cybus-helm-charts/metrics.md). # Configuring Prometheus Metrics The `connectware` and `connectware-agent` Helm charts can expose Prometheus metrics for their components and create Kubernetes `ServiceMonitor` custom resources so a Prometheus Operator installation can discover and scrape them automatically. [Prometheus Operator](https://prometheus-operator.dev) is a Kubernetes controller that manages Prometheus instances declaratively. Instead of maintaining a static scrape configuration, you create `ServiceMonitor` resources that describe where and how Prometheus should scrape a service. It is commonly installed as part of the [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) Helm chart. {% hint style="info" %} Creating `ServiceMonitor` resources requires the Prometheus Operator [ServiceMonitor custom resource definition](https://prometheus-operator.dev/docs/getting-started/design/#servicemonitor) to be installed in your cluster. If it is not installed, leave every `serviceMonitor.enabled` value set to `false` and see [Scraping Connectware Metrics with Self-Managed Prometheus](/2-6-0/monitoring/connectware-metrics/scraping-metrics.md) for alternative scraping options. {% endhint %} ## Service Monitors A `ServiceMonitor` is a Prometheus Operator custom resource that tells Prometheus which service to scrape and how. Rather than editing the Prometheus scrape configuration by hand, you let the charts generate these resources for you. Both charts can create `ServiceMonitor` resources for the components and agents that expose a metrics endpoint. Set `serviceMonitor.enabled` to `true` on a component, an agent, or globally, and the chart generates a `ServiceMonitor` that Prometheus Operator discovers and scrapes automatically. Every metrics values table under [Configuration Values](#configuration-values) includes a `serviceMonitor.*` block. If your Prometheus Operator installation restricts which `ServiceMonitor` resources it selects through a `serviceMonitorSelector`, set the matching labels via `serviceMonitor.labels`. Otherwise the generated `ServiceMonitor` is ignored. If Prometheus Operator is not available in your cluster, see [Scraping Connectware Metrics](/2-6-0/monitoring/connectware-metrics/scraping-metrics.md) for static configuration and Kubernetes Service Discovery alternatives. ## Components with Metrics Support {% tabs %} {% tab title="connectware" %} ## connectware Helm Chart The `connectware` Helm chart configures metrics on the components listed below. | Component | Helm Value | | ------------------------ | -------------------------------- | | All components (global) | `global.metrics` | | Auth Server | `authServer.metrics` | | Broker | `broker.metrics` | | NATS | `nats.metrics` | | Protocol Mapper | `protocolMapper.metrics` | | Resource Status Tracking | `resourceStatusTracking.metrics` | | Service Manager | `serviceManager.metrics` | Auth Server, Protocol Mapper, Resource Status Tracking, and Service Manager expose a metrics endpoint directly on containerPort `9184`. Broker exposes a metrics endpoint directly on containerPort `8888`. NATS does not expose its own metrics endpoint. Instead, `nats.metrics.enabled` deploys a Prometheus exporter as a sidecar next to the NATS container. {% endtab %} {% tab title="connectware-agent" %} ## connectware-agent Helm Chart The `connectware-agent` Helm chart configures metrics on protocol-mapper agents. Each agent exposes a metrics endpoint on containerPort `9184`, the same as the in-cluster Protocol Mapper. | Scope | Helm Value | | --------------------------- | ------------------------------------- | | Defaults for all agents | `protocolMapperAgentDefaults.metrics` | | Override for a single agent | `protocolMapperAgents[*].metrics` | A per-agent `metrics` value always takes precedence over the defaults set in `protocolMapperAgentDefaults.metrics`. {% endtab %} {% endtabs %} ## Configuration Values The following Helm values control metrics for each chart. {% tabs %} {% tab title="connectware" %} ## connectware Helm Chart The `connectware` Helm chart groups metrics values by component. Every metrics endpoint also accepts a `serviceMonitor.*` block for creating a Prometheus Operator `ServiceMonitor` resource. ### Global Metrics Values under `global.metrics` apply as defaults to every component that supports metrics. A component-level `metrics` value always takes precedence over the global value. | Value | Description | | ------------------------------------------------- | ----------------------------------------------------------------------------------- | | `global.metrics.enabled` | Enables metrics in every component that supports it. Default: `true`. | | `global.metrics.collectIntervalMs` | How often collected values are stored into Prometheus counters, in milliseconds. | | `global.metrics.rateLimit.count` | Maximum number of scrape requests allowed within the rate limit window. | | `global.metrics.rateLimit.windowMs` | Duration of the rate limit window, in milliseconds. | | `global.metrics.serviceMonitor.enabled` | Creates a `ServiceMonitor` for every component that supports it. Default: `false`. | | `global.metrics.serviceMonitor.namespace` | Namespace for the generated `ServiceMonitor` resources. Default: release namespace. | | `global.metrics.serviceMonitor.labels` | Labels applied to every generated `ServiceMonitor`. | | `global.metrics.serviceMonitor.jobLabel` | Label whose value replaces the job name in the scraped metrics. | | `global.metrics.serviceMonitor.interval` | Prometheus scrape interval for the `ServiceMonitor` endpoints. | | `global.metrics.serviceMonitor.scrapeTimeout` | Prometheus scrape timeout for the `ServiceMonitor` endpoints. | | `global.metrics.serviceMonitor.metricRelabelings` | Metric relabeling rules applied to samples before ingestion. | | `global.metrics.serviceMonitor.relabelings` | Relabeling rules applied to scrape targets before scraping. | {% hint style="info" %} `global.metrics.collectIntervalMs`, `global.metrics.rateLimit.count`, and `global.metrics.rateLimit.windowMs` only apply to Auth Server, Protocol Mapper, Resource Status Tracking, and Service Manager. They have no effect on NATS or Broker. {% endhint %} ### Standard Metrics Endpoints Auth Server, Protocol Mapper, Resource Status Tracking, and Service Manager share the same metrics endpoint configuration. Replace `${COMPONENT_NAME}` with `authServer`, `protocolMapper`, `resourceStatusTracking`, or `serviceManager`. | Value | Description | | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `${COMPONENT_NAME}.metrics.enabled` | Enables the metrics endpoint, a dedicated metrics service, and containerPort `9184`. Inherits `global.metrics.enabled` when unset. | | `${COMPONENT_NAME}.metrics.collectIntervalMs` | How often collected values are stored into Prometheus counters, in milliseconds. | | `${COMPONENT_NAME}.metrics.rateLimit.count` | Maximum number of scrape requests allowed within the rate limit window. | | `${COMPONENT_NAME}.metrics.rateLimit.windowMs` | Duration of the rate limit window, in milliseconds. | | `${COMPONENT_NAME}.metrics.serviceMonitor.enabled` | Creates a `ServiceMonitor` for the component. | | `${COMPONENT_NAME}.metrics.serviceMonitor.namespace` | Namespace for the `ServiceMonitor`. | | `${COMPONENT_NAME}.metrics.serviceMonitor.labels` | Labels applied to the `ServiceMonitor`. | | `${COMPONENT_NAME}.metrics.serviceMonitor.jobLabel` | Label whose value replaces the job name in the scraped metrics. | | `${COMPONENT_NAME}.metrics.serviceMonitor.interval` | Prometheus scrape interval for the `ServiceMonitor` endpoint. | | `${COMPONENT_NAME}.metrics.serviceMonitor.scrapeTimeout` | Prometheus scrape timeout for the `ServiceMonitor` endpoint. | | `${COMPONENT_NAME}.metrics.serviceMonitor.metricRelabelings` | Metric relabeling rules applied to samples before ingestion. | | `${COMPONENT_NAME}.metrics.serviceMonitor.relabelings` | Relabeling rules applied to the scrape target before scraping. | ### NATS NATS exposes metrics through a Prometheus exporter sidecar rather than through a metrics endpoint of its own, so its values differ from the other components. | Value | Description | | ----------------------------------------------- | ----------------------------------------------------------------- | | `nats.metrics.enabled` | Deploys a Prometheus exporter sidecar next to the NATS container. | | `nats.metrics.resources.requests.cpu` | CPU request for the exporter sidecar. | | `nats.metrics.resources.requests.memory` | Memory request for the exporter sidecar. | | `nats.metrics.resources.limits.cpu` | CPU limit for the exporter sidecar. | | `nats.metrics.resources.limits.memory` | Memory limit for the exporter sidecar. | | `nats.metrics.serviceMonitor.enabled` | Creates a `ServiceMonitor` for the NATS exporter. | | `nats.metrics.serviceMonitor.namespace` | Namespace for the `ServiceMonitor`. | | `nats.metrics.serviceMonitor.labels` | Labels applied to the `ServiceMonitor`. | | `nats.metrics.serviceMonitor.jobLabel` | Label whose value replaces the job name in the scraped metrics. | | `nats.metrics.serviceMonitor.interval` | Prometheus scrape interval for the `ServiceMonitor` endpoint. | | `nats.metrics.serviceMonitor.scrapeTimeout` | Prometheus scrape timeout for the `ServiceMonitor` endpoint. | | `nats.metrics.serviceMonitor.metricRelabelings` | Metric relabeling rules applied to samples before ingestion. | | `nats.metrics.serviceMonitor.relabelings` | Relabeling rules applied to the scrape target before scraping. | ### Broker Broker exposes a metrics endpoint on containerPort `8888`, but does not accept the shared `collectIntervalMs` or `rateLimit.*` tuning values. | Value | Description | | ------------------------------------------------- | --------------------------------------------------------------- | | `broker.metrics.enabled` | Enables the Broker metrics endpoint. | | `broker.metrics.serviceMonitor.enabled` | Creates a `ServiceMonitor` for Broker. | | `broker.metrics.serviceMonitor.namespace` | Namespace for the `ServiceMonitor`. | | `broker.metrics.serviceMonitor.labels` | Labels applied to the `ServiceMonitor`. | | `broker.metrics.serviceMonitor.jobLabel` | Label whose value replaces the job name in the scraped metrics. | | `broker.metrics.serviceMonitor.interval` | Prometheus scrape interval for the `ServiceMonitor` endpoint. | | `broker.metrics.serviceMonitor.scrapeTimeout` | Prometheus scrape timeout for the `ServiceMonitor` endpoint. | | `broker.metrics.serviceMonitor.metricRelabelings` | Metric relabeling rules applied to samples before ingestion. | | `broker.metrics.serviceMonitor.relabelings` | Relabeling rules applied to the scrape target before scraping. | | {% endtab %} | | {% tab title="connectware-agent" %} ## connectware-agent Helm Chart The `connectware-agent` Helm chart groups metrics values into defaults that apply to every agent and per-agent overrides. A per-agent value always takes precedence over the matching default. ### Defaults for All Agents Values under `protocolMapperAgentDefaults.metrics` apply to every agent unless overridden for a specific agent. | Value | Description | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | `protocolMapperAgentDefaults.metrics.enabled` | Enables the metrics endpoint, a dedicated metrics service, and containerPort `9184`. | | `protocolMapperAgentDefaults.metrics.collectIntervalMs` | How often collected values are stored into Prometheus counters, in milliseconds. | | `protocolMapperAgentDefaults.metrics.rateLimit.count` | Maximum number of scrape requests allowed within the rate limit window. | | `protocolMapperAgentDefaults.metrics.rateLimit.windowMs` | Duration of the rate limit window, in milliseconds. | | `protocolMapperAgentDefaults.metrics.serviceMonitor.enabled` | Creates a `ServiceMonitor` for every agent. | | `protocolMapperAgentDefaults.metrics.serviceMonitor.namespace` | Namespace for the generated `ServiceMonitor` resources. | | `protocolMapperAgentDefaults.metrics.serviceMonitor.labels` | Labels applied to every generated `ServiceMonitor`. | | `protocolMapperAgentDefaults.metrics.serviceMonitor.jobLabel` | Label whose value replaces the job name in the scraped metrics. | | `protocolMapperAgentDefaults.metrics.serviceMonitor.interval` | Prometheus scrape interval for the `ServiceMonitor` endpoints. | | `protocolMapperAgentDefaults.metrics.serviceMonitor.scrapeTimeout` | Prometheus scrape timeout for the `ServiceMonitor` endpoints. | | `protocolMapperAgentDefaults.metrics.serviceMonitor.metricRelabelings` | Metric relabeling rules applied to samples before ingestion. | | `protocolMapperAgentDefaults.metrics.serviceMonitor.relabelings` | Relabeling rules applied to scrape targets before scraping. | ### Overrides for a Single Agent Values under `protocolMapperAgents[*].metrics` override the defaults for one agent. Only the values you set are overridden; the rest continue to inherit from `protocolMapperAgentDefaults.metrics`. | Value | Description | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | | `protocolMapperAgents[*].metrics.enabled` | Enables the metrics endpoint, a dedicated metrics service, and containerPort `9184`. | | `protocolMapperAgents[*].metrics.collectIntervalMs` | How often collected values are stored into Prometheus counters, in milliseconds. | | `protocolMapperAgents[*].metrics.rateLimit.count` | Maximum number of scrape requests allowed within the rate limit window. | | `protocolMapperAgents[*].metrics.rateLimit.windowMs` | Duration of the rate limit window, in milliseconds. | | `protocolMapperAgents[*].metrics.serviceMonitor.enabled` | Creates a `ServiceMonitor` for the agent. | | `protocolMapperAgents[*].metrics.serviceMonitor.namespace` | Namespace for the `ServiceMonitor`. | | `protocolMapperAgents[*].metrics.serviceMonitor.labels` | Labels applied to the `ServiceMonitor`. | | `protocolMapperAgents[*].metrics.serviceMonitor.jobLabel` | Label whose value replaces the job name in the scraped metrics. | | `protocolMapperAgents[*].metrics.serviceMonitor.interval` | Prometheus scrape interval for the `ServiceMonitor` endpoint. | | `protocolMapperAgents[*].metrics.serviceMonitor.scrapeTimeout` | Prometheus scrape timeout for the `ServiceMonitor` endpoint. | | `protocolMapperAgents[*].metrics.serviceMonitor.metricRelabelings` | Metric relabeling rules applied to samples before ingestion. | | `protocolMapperAgents[*].metrics.serviceMonitor.relabelings` | Relabeling rules applied to the scrape target before scraping. | When the `connectware-agent` Helm chart is deployed as a subchart of the `connectware` Helm chart, agents also inherit any unset metrics value from the parent chart's `global.metrics.*`. {% endtab %} {% endtabs %} ## Configuring Metrics {% tabs %} {% tab title="connectware" %} ## connectware Helm Chart ### Enabling Metrics for All Components Metrics are enabled by default in the `connectware` Helm chart. To enable metrics explicitly for every component that supports it, set `global.metrics.enabled` to `true`: {% code title="values.yaml" lineNumbers="true" %} ```yaml global: metrics: enabled: true ``` {% endcode %} To disable metrics everywhere, set `global.metrics.enabled` to `false`. ### Enabling Metrics for a Single Component To enable or disable metrics for one component without changing the global default, set `metrics.enabled` under that component's own configuration section. A component-level value always takes precedence over `global.metrics.enabled`. The following example disables metrics globally, then re-enables them only for Protocol Mapper: {% code title="values.yaml" lineNumbers="true" %} ```yaml global: metrics: enabled: false protocolMapper: metrics: enabled: true ``` {% endcode %} ### Configuring the Scrape Rate Limit Set `rateLimit.count` and `rateLimit.windowMs` to cap how many scrape requests a component's metrics endpoint accepts within a time window. This protects the component from excessive scrape traffic, for example, if a Prometheus instance is misconfigured with a scrape interval that is too short. The following example allows up to ten scrape requests every minute for Protocol Mapper: {% code title="values.yaml" lineNumbers="true" %} ```yaml protocolMapper: metrics: rateLimit: count: 10 windowMs: 60000 ``` {% endcode %} ### Creating a ServiceMonitor for Prometheus Operator A `ServiceMonitor` is a Prometheus Operator custom resource that tells Prometheus where and how to scrape a target. Set `serviceMonitor.enabled` to `true` on a component to create one, so Prometheus Operator discovers and scrapes the component automatically. {% hint style="warning" %} `ServiceMonitor` is a Kubernetes Custom Ressource and your cluster needs to have the matching Custom Resource Definition installed, or the Helm installation will fail. Ensure you have [Prometheus Operator](https://prometheus-operator.dev/docs/getting-started/introduction/) and its Custom Resource Definitions installed before proceeding. {% endhint %} The following example creates a `ServiceMonitor` for Service Manager with a 30-second scrape interval: {% code title="values.yaml" lineNumbers="true" %} ```yaml serviceManager: metrics: enabled: true serviceMonitor: enabled: true interval: 30s scrapeTimeout: 10s ``` {% endcode %} {% hint style="info" %} If your Prometheus Operator installation restricts which `ServiceMonitor` resources it selects through a `serviceMonitorSelector`, set `serviceMonitor.labels` to match that selector. Otherwise, Prometheus Operator ignores the generated `ServiceMonitor`. {% endhint %} ### Setting resources for the NATS Prometheus Exporter NATS requires its own Prometheus exporter sidecar, which is enabled by default. Set compute resources for the sidecar under `nats.metrics.resources`: {% code title="values.yaml" lineNumbers="true" %} ```yaml nats: metrics: enabled: true resources: requests: cpu: 50m memory: 64Mi limits: cpu: 100m memory: 128Mi serviceMonitor: enabled: true ``` {% endcode %} ### Disabling NATS Prometheus Exporter NATS requires its own Prometheus exporter sidecar, which is enabled by default. If you want to disable this sidecar, set `nats.metrics.enabled` to `false`: {% code title="values.yaml" lineNumbers="true" %} ```yaml nats: metrics: enabled: false ``` {% endcode %} {% endtab %} {% tab title="connectware-agent (Standalone)" %} ## connectware-agent Helm Chart (Standalone) Use this tab if you deploy the `connectware-agent` Helm chart on its own. If you deploy it as a subchart of the `connectware` Helm chart, see the **connectware-agent (As Subchart)** tab instead. ### Enabling Metrics for All Agents Set defaults under `protocolMapperAgentDefaults.metrics`. Every agent inherits these values unless overridden per agent: {% code title="values.yaml" lineNumbers="true" %} ```yaml protocolMapperAgentDefaults: metrics: enabled: true collectIntervalMs: 5000 protocolMapperAgents: - name: bender-robots - name: welder-robots ``` {% endcode %} To disable metrics for every agent, set `protocolMapperAgentDefaults.metrics.enabled` to `false`. ### Overriding Metrics for a Single Agent Add a `metrics` block to an entry in `protocolMapperAgents` to override the defaults for that agent only. The following example raises the rate limit for `high-frequency-agent`, while `bender-robots` keeps the defaults: {% code title="values.yaml" lineNumbers="true" %} ```yaml protocolMapperAgentDefaults: metrics: enabled: true protocolMapperAgents: - name: bender-robots - name: high-frequency-agent metrics: rateLimit: count: 10 windowMs: 60000 ``` {% endcode %} To disable metrics for a single agent while keeping them enabled elsewhere, set `metrics.enabled` to `false` under that agent's entry. ### Creating a ServiceMonitor for Prometheus Operator Set `metrics.serviceMonitor.enabled` to `true` under `protocolMapperAgentDefaults.metrics` to create a `ServiceMonitor` for every agent. Set it under a specific agent's entry to create one for that agent only. {% code title="values.yaml" lineNumbers="true" %} ```yaml protocolMapperAgentDefaults: metrics: enabled: true serviceMonitor: enabled: true interval: 30s scrapeTimeout: 10s protocolMapperAgents: - name: bender-robots - name: welder-robots ``` {% endcode %} {% endtab %} {% tab title="connectware-agent (As Subchart)" %} ## connectware-agent Helm Chart (As Subchart) Use this tab if you deploy the `connectware-agent` Helm chart as a subchart of the `connectware` Helm chart. If you deploy it on its own, see the **connectware-agent (Standalone)** tab instead. When deployed as a subchart, nest all `connectware-agent` values under the `connectwareAgent` key. Agents also inherit any unset metrics value from the parent chart's `global.metrics.*`. ### Inheriting Metrics from the Parent Chart With no per-agent overrides, every agent inherits `global.metrics.*` from the `connectware` Helm chart. The following example disables metrics globally, and every agent picks up those settings automatically: {% code title="values.yaml" lineNumbers="true" %} ```yaml global: metrics: enabled: false connectwareAgent: protocolMapperAgents: - name: bender-robots - name: welder-robots ``` {% endcode %} ### Overriding Metrics for All Agents To override the parent's `global.metrics` for every agent, set values under `connectwareAgent.protocolMapperAgentDefaults.metrics`: {% code title="values.yaml" lineNumbers="true" %} ```yaml connectwareAgent: protocolMapperAgentDefaults: metrics: collectIntervalMs: 10000 protocolMapperAgents: - name: bender-robots - name: welder-robots ``` {% endcode %} ### Overriding Metrics for a Single Agent Add a `metrics` block to an entry in `connectwareAgent.protocolMapperAgents` to override values for that agent only: {% code title="values.yaml" lineNumbers="true" %} ```yaml connectwareAgent: protocolMapperAgentDefaults: metrics: enabled: true protocolMapperAgents: - name: bender-robots - name: high-frequency-agent metrics: rateLimit: count: 10 windowMs: 60000 ``` {% endcode %} {% endtab %} {% endtabs %} ## Applying Configuration Changes After editing your `values.yaml` file, apply the changes by running the `helm upgrade` command. For details, see [Applying Helm Configuration Changes](/2-6-0/cybus-helm-charts/working-with-cybus-helm-charts.md#applying-helm-configuration-changes). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cybus.io/2-6-0/cybus-helm-charts/working-with-cybus-helm-charts/metrics.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.