Upgrading the Collection Agent

Overview Copied

Before upgrading the Collection Agent, take note of the following:

• Collection Agent 4.x is only compatible and packaged with Netprobe 6.7.x and higher, and requires Java 17.x.
• Collection Agent 3.x is only compatible with Netprobe 6.0.x and higher, but is only packaged with Netprobe 6.0.x to Netprobe 6.6.x. Collection Agent 3.x requires Java 11.x.
• If you are using Collection Agent 2.x, it is only compatible and packaged with Netprobe 5.x.

Upgrading the Collection Agent from 3.x to 4.x Copied

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 — MongoDB V4 built in mapping is available and must be used when setting up the MongoDB plugin.
• Prometheus plugin

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 Copied

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 health-check section is renamed to health-probe.
• The metrics section is renamed to self-metrics.
• In the self-metrics section, the delivery-mode, disable-windowing, and properties are no longer supported.

Below is an example of a valid self-monitoring configuration:

monitoring:

  # Optional. Defaults to true.
  enabled: true

  # Health and metrics reporting interval in milliseconds. Defaults to 10 seconds.
  reporting-interval: 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.
  health-probe:

    # Optional. Defaults to true.
    enabled: true

    # HTTP listen port, defaults to 8080.
    listen-port: 8080

  # Agent self metrics.
  self-metrics:

    # 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 Copied

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 Copied

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. 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 label-mode settings for both KubernetesMetricsCollector and KubernetesLogCollector are removed. In this version, the Kubernetes object labels are always collected as attributes. You must also remove label-mode 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.
  label-mode: [ 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
        class-name: 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 Copied

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.