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
healthCheck
section is renamed tohealthProbe
. - The
metrics
section is renamed toselfMetrics
. - In the
selfMetrics
section, thedeliveryMode
,disableWindowing
, andproperties
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.
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 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
anditrs_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 thedata_kind
anditrs_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
labelMode
settings for both KubernetesMetricsCollector and KubernetesLogCollector are removed. In this version, the Kubernetes object labels are always collected as attributes. You must also removelabelMode
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 tokube_
, for examplekubernetes_pod_cpu_usage
is changed tokube_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 tonode
, andpod_name
is changed topod
. 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.