--- title: "Upgrading the Collection Agent" description: "" url: "https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/collection-agent/upgrade-collection-agent/index.html" --- ## Overview Before upgrading the Collection Agent, take note of the following: - Collection Agent 6.x is only compatible and packaged with Netprobe 7.5.x and higher. - Collection Agent 5.x is only compatible and packaged with Netprobe 7.1.x and higher, and requires Java 21.x. - Collection Agent 4.x is only compatible and packaged with Netprobe 6.7.x and higher, and requires Java 17.x. ## Upgrading the Collection Agent from 5.x to 6.x There are no breaking changes when upgrading from version 5.x to version 6.x. ## Upgrading the Collection Agent from 4.x to 5.x Beginning Geneos 7.1.x, the Collection Agent and Collection Agent plugins have been upgraded to version 5.0.0. Consequently, the minimum Java version requirement for both the Collection Agent and Collection Agent plugins version 5.0.0 is Java 21. This may require you to upgrade the Java versions on the machines where Collection Agent is running. ## Upgrading the Collection Agent from 3.x to 4.x When upgrading the Collection Agent from 3.x to 4.x, take note that Collection Agent 4.x is only compatible and packaged with Netprobe 6.7.x and higher, and requires Java 17. Additionally, refer to the following for the latest Collection Agent plugins configuration: - [MongoDB plugin](https://docs.itrsgroup.com/docs/geneos/collection/mongodb/current/user-guide/mongodb/index.html#set-up-your-collection-agent-plugin) — **MongoDB V4** built in mapping is available and must be used when setting up the MongoDB plugin. - [Prometheus plugin](https://docs.itrsgroup.com/docs/geneos/collection/prometheus/current/user-guide/prometheus/index.html) **Note** You can still use the **Azure Monitor V3**, **Collection Agent V3**, and **Prometheus V3** built in mappings when configuring Collection Agent 4.x since these mappings have not been changed. ## Upgrading the Collection Agent from 2.x to 3.x When upgrading the Collection Agent from 2.x to 3.x, take note of the following configuration changes related to the `monitoring` (self-monitoring) configuration: - The `healthCheck` section is renamed to `healthProbe`. - The `metrics` section is renamed to `selfMetrics`. - In the `selfMetrics` section, the `deliveryMode`, `disableWindowing`, and `properties` are no longer supported. Below is an example of a valid self-monitoring configuration: ```yaml monitoring: # Optional. Defaults to true. enabled: true # Health and metrics reporting interval in milliseconds. Defaults to 10 seconds. reportingInterval: 10000 # The agent will listen on an HTTP port so that an external system can probe its health. # In Kubernetes, this can be used in conjunction with the readiness/liveness probes. # 200 is returned if the agent is started, 500 otherwise. healthProbe: # Optional. Defaults to true. enabled: true # HTTP listen port, defaults to 8080. listenPort: 8080 # Agent self metrics. selfMetrics: # Whether to enable self metric collection (optional, defaults to true). enabled: true # Dimensions to add to all self metrics from this agent (optional). dimensions: custom: value ``` The Collection Agent self-monitoring dimension `app_name` is changed to `app`. Ensure the Dynamic Entity mapping settings in your Gateway configuration are updated to reflect this change in dimension name. A new built-in mapping called **Collection Agent V3** is now available in the Gateway Setup Editor. This also changes the naming of Geneos data items such as entities, samplers, and dataviews. Ensure all x-paths that refer to Collection Agent self-monitoring data items in Geneos are correct and updated properly. ## All Collection Agent plugins All Collection Agent plugins remove the `data_kind` and `itrs_source` dimensions, and replace them with the new `__itrs_namespace__` dimension. For the Azure plugin, for example, you have a dimension `__itrs_namespace__` with the value `itrsgroup.com/c2/azure-plugin`: - Both `data_kind` and `itrs_source` dimensions are typically not used when mapping directly to Geneos data items such as entities, samplers, and dataviews. However, it is likely they are used in the mapping filters to separate out data points from different plugins. - If you have built-in mappings for your Dynamic Entity configuration in the Gateway, you must change it to a **V3** mapping. For the Azure plugin, select **Azure Monitor V3** built-in mapping. If you have custom mappings, make sure that the new `__itrs_namespace__` dimension replaces both the `data_kind` and `itrs_source` dimensions . ## Kubernetes plugin If you deployed Netprobe and Collection Agent in Kubernetes using the ITRS Helm chart, then you must upgrade to the latest Helm chart as needed. For more information about Helm, see [Installation using Helm](https://docs.itrsgroup.com/docs/geneos/7.11.0/administration/orchestrated-environments/installation-using-helm/index.html). This ensures both Netprobe and Collection Agent are upgraded with the correct configuration. If you deployed Netprobe and Collection Agent manually using manifests, then you must ensure the Collection Agent configuration is updated and take note of these changes: - The `labelMode` settings for both **KubernetesMetricsCollector** and **KubernetesLogCollector** are removed. In this version, the Kubernetes object labels are always collected as attributes. You must also remove `labelMode` settings in your Collection Agent configuration. ``` # How to collect Kubernetes object labels. # legacy: Default legacy behaviour (before 2.3.0) - metrics collector ignores labels. # attributes: Labels are collected as attributes. # disabled: Labels are ignored and not collected. # # If the KubernetesLogCollector is also configured, it must have the same setting. labelMode: [ legacy | attributes | disabled ] ``` - The namespace filtering settings for the **KubernetesLogCollector** is updated. Ensure that you update your Collection Agent configuration to verify the namespace filtering syntax is correct. An example of the previous setting: ``` # When multiple entries are defined, they are treated as an "OR" - a log file matching any rule # will be included. # # Defaults to undefined (include all). includes: - namespace: ns1 - namespace: ns2 - "*glob-pattern1*" - "*glob-pattern2*" # Exclude specific logs from processing. See the "includes" section for details. # # If a log file matches both an include and exclude, the exclusion takes precedence. # Defaults to undefined (no exclusions). excludes: - namespace: ns3 - "*glob-pattern*" ``` Updated the new setting to: ``` # Namespaces in which to collect logs. Defaults to all namespaces. - ns1 - ns2 ``` - The Kubernetes specific workflow processor, **KubernetesEnricher**, is removed. This previously added the **kubernetes\_app\_name** dimension by default when it is enabled. You must update the Collection Agent configuration to remove the **KubernetesEnricher** workflow processor: ``` workflow: common: processors: - type: plugin name: kube-enricher className: KubernetesEnricher # Name of the enriched dimension that represents the application name. Default value shown. app-dimension: kubernetes_app_name ``` Below is an example of a replacement configuration using the common workflow processor to add custom dimensions: ``` workflow: common: processors: - type: enrichment name: enricher overwrite: false dimensions: kubernetes_app_name: ${env:APP_NAME} ``` - The `kubernetes_` metric name prefix is changed to `kube_`, for example `kubernetes_pod_cpu_usage` is changed to `kube_pod_cpu_usage`. This will result in row and column name changes for the dataviews produced by the Kubernetes plugin. Ensure all x-paths that refer to Kubernetes plugins are checked and updated properly. - The `_name` suffix is removed from the dimension names used in the Kubernetes plugin. For example, `node_name` is changed to `node`, and `pod_name` is changed to `pod`. Ensure the Dynamic Entity mapping settings in your Gateway configuration are updated to reflect this change in dimension name. This changes the naming of Geneos data items such as entities, samplers, and dataviews. Ensure all x-paths that refer to Kubernetes plugins are checked and updated properly. Below is a list of dimension names affected by this change: - `container` - `container_id` - `daemonset` - `deployment` - `interface` - `job` - `kind` - `namespace` - `node` - `pod` - `quota` - `replicaset` - `resource` - `statefulset` - `stream` - `volume` ## AWS plugin Previously, AWS plugin metric names and dimension names followed this format: `cpu_utilization`, `region`. In this version, this is changed to be consistent with the AWS format, for example, `CPUUtilization`, `Region`. Ensure the Dynamic Entity mapping settings in your Gateway configuration are updated to reflect this change in dimension name. This changes the naming of Geneos data items such as entities, samplers, dataviews, rows, and columns. Ensure all x-paths that refer to the AWS plugins generated data are checked and updated properly.