Skip to content

Commit 03a0b57

Browse files
rapphilrapphil
authored
Merge pull request #674 from aws-otel/rapphil-migration-guide-v0.35.0
Feat: Add migration guide for ADOT collector v0.35.0
2 parents 83e3c07 + 0b9a439 commit 03a0b57

File tree

4 files changed

+148
-8
lines changed

4 files changed

+148
-8
lines changed

‎src/content/BlogPosts/blogPosts.yaml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,13 @@ description:
66
path: /blog
77

88
blogs:
9+
- title: "Migration guide for the ADOT collector v0.35.0 - Prometheus exporters"
10+
author: "Raphael Silva"
11+
date: "30-November-2023"
12+
body:
13+
"Guide containing details about how to migrate to ADOT collector v0.35.0 if you are using the Prometheus exporter or Prometheus Remote Write exporter"
14+
link: "/docs/migrating-to-collector-v0.35.0"
15+
916
- title: "AWS Distro for OpenTelemetry EKS Add-on v0.88.0-eksbuild.1 is now available"
1017
author: "Huy Vo"
1118
date: "20-November-2023"

‎src/content/Blogs/ReleaseBlogs/aws-distro-for-opentelemetry-collector-v0.35.0.mdx

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -37,17 +37,14 @@ Collector configuration.
3737
`adot.exporter.awscloudwatchlogs
3838
`adot.extension.file_storage`
3939

40-
** Important: ADOT Collector v0.35.0 Breaking Change **
40+
** Important: ADOT Collector v0.35.0 Breaking Changes **
4141

42-
Users of the `statsd` receiver, please refer to GitHub Issue - [Warning: StatsD Receiver → EMF Exporter
42+
* Users of the `statsd` receiver, please refer to GitHub Issue - [Warning: StatsD Receiver → EMF Exporter
4343
Metric Pipeline Breaking Change](https://github.com/aws-observability/aws-otel-collector/issues/2249) for information on a breaking change.
44-
45-
** Important: ADOT Collector v0.35.0 Breaking Change
46-
47-
Users of the `awscontainerinsightreceiver`, please refer to the [GitHub Issue - Warning: Container Image Default User Change → Important
44+
* Users of the `awscontainerinsightreceiver`, please refer to the [GitHub Issue - Warning: Container Image Default User Change → Important
4845
consideration for AWSContainerInsightReceiver](https://github.com/aws-observability/aws-otel-collector/issues/2317) for more information on a breaking change.
49-
50-
-
46+
* Users of the `prometheusremotewrite` and `prometheus` exporters, please refer to our [migration guide](/docs/migrating-to-collector-v0.35.0) and
47+
[GitHub Issue - Warning: ADOT Collector v0.35.0 breaking changes - Normalization of metrics in prometheus exporters](https://github.com/aws-observability/aws-otel-collector/issues/2367)
5148

5249
Detailed release notes are available via - [GitHub](https://github.com/aws-observability/aws-otel-collector/releases).
5350
All code changes are upstream in the respective OpenTelemetry project components.

‎src/content/Blogs/migrating-to-collector-v0.35.0.mdx

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: 'Migration guide for the ADOT collector v0.35.0 - Prometheus exporters'
3+
description:
4+
This blog post describes the process of migrating to the ADOT collector v0.35.0. This guide is necessary due to upcoming breaking changes present in the
5+
Prometheus exporter and Prometheus remote write exporter components.
6+
---
7+
8+
## What is happening?
9+
10+
Starting with version v0.85.0 of the upstream OpenTelemetry collector, the normalization of metrics when converting from OpenTelemetry metrics to Prometheus will be enabled by default.
11+
12+
## When will this happen?
13+
14+
The ADOT collector will start adopting the upstream behavior for name normalization of Prometheus metrics on version v0.35.0.
15+
16+
## Who is affected and what to expect?
17+
18+
You are affected if you are using one of the following components present in the ADOT collector: [prometheus exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/prometheusexporter#prometheus-exporter) and [prometheus remote write exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/prometheusremotewriteexporter#prometheus-remote-write-exporter).
19+
20+
If you don’t do anything, the name of the metrics exported by the collector using these components will be normalized according to well defined rules [1,2]. These rules are applied so best practices are applied to the naming of metrics [3].
21+
22+
Notably the following changes will enter in effect:
23+
24+
* The unit of the metrics will be appended as suffix to the metrics exported by Prometheus.
25+
* Counters will have a `_total` suffix.
26+
27+
Examples:
28+
29+
|Type |Name |Unit |Prometheus Metric exported|
30+
|---|---|---|---|
31+
|Gauge |system.filesystem.usage |By |system_filesystem_usage_bytes |
32+
|Gauge |system.network.dropped |packets |system_network_dropped_packets |
33+
|Counter |system.network.dropped |packets |system_network_dropped_packets_total |
34+
|Gauge |system.cpu.utilization |1 |system_cpu_utilization_ratio |
35+
36+
The feature gate `pkg.translator.prometheus.NormalizeName` is used to control the normalization behavior. If the feature gate is disabled, there won’t be name normalization. Besides that, both components added a configuration option to control the normalization behaviour in the component level, the `add_metric_suffixes` property. This configuration option is only honoured if the feature gate is enabled.
37+
38+
In the ADOT collector v0.34.0, the feature gate `pkg.translator.prometheus.NormalizeName` is disabled by default. In the collector v0.35.0, this feature gate will be enabled by default.
39+
40+
* [1] https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/pkg/translator/prometheus
41+
* [2] https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1
42+
* [3] https://prometheus.io/docs/practices/naming/
43+
44+
45+
## What action items do I need to take?
46+
47+
### If you want to upgrade to the ADOT collector v0.35.0 without name normalization
48+
49+
This path is recommended for users who want to retain the metrics names unchanged after upgrading to the ADOT collector v0.35.0. This will guarantee that dashboards and alarms remain functional after the upgrade.
50+
51+
The following step by step guide is provided to guarantee a safe and gradual migration.
52+
53+
Steps:
54+
55+
1. Upgrade the ADOT collector to v0.34.0.
56+
2. Modify/review the collector configuration for the components Prometheus remote write exporter and Prometheus exporter. They **must** add the property `add_metric_suffixes: false` to the configuration section of these components.
57+
Example:
58+
```yaml
59+
prometheusremotewrite:
60+
endpoint: http://example.com
61+
add_metric_suffixes: false # <-- Disable normalization
62+
resource_to_telemetry_conversion:
63+
enabled: true
64+
auth:
65+
authenticator: sigv4auth
66+
```
67+
```yaml
68+
exporters:
69+
prometheus:
70+
endpoint: "1.2.3.4:1234"
71+
namespace: test-space
72+
const_labels:
73+
label1: value1
74+
"another label": spaced value
75+
send_timestamps: true
76+
metric_expiration: 180m
77+
enable_open_metrics: true
78+
add_metric_suffixes: false # <-- Disable normalization
79+
resource_to_telemetry_conversion:
80+
enabled: true
81+
```
82+
3. Upgrade the ADOT collector to v0.35.0.
83+
84+
### If you recently upgraded to ADOT collector v0.35.0
85+
86+
This path is recommended for users that are already using the ADOT collector v0.35.0. The following steps are recommended:
87+
88+
* If you want to keep metric names as collected by the ADOT collector, e.g. untransformed, you should modify/review the collector configuration for the components Prometheus remote write exporter and Prometheus exporter. You **must** have the property `add_metric_suffixes: false` in the configuration section of these components.
89+
90+
Example:
91+
92+
```yaml
93+
prometheusremotewrite:
94+
endpoint: http://example.com
95+
add_metric_suffixes: false # <-- Disable normalization
96+
resource_to_telemetry_conversion:
97+
enabled: true
98+
auth:
99+
authenticator: sigv4auth
100+
```
101+
102+
```yaml
103+
exporters:
104+
prometheus:
105+
endpoint: "1.2.3.4:1234"
106+
namespace: test-space
107+
const_labels:
108+
label1: value1
109+
"another label": spaced value
110+
send_timestamps: true
111+
metric_expiration: 180m
112+
enable_open_metrics: true
113+
add_metric_suffixes: false # <-- Disable normalization
114+
resource_to_telemetry_conversion:
115+
enabled: true
116+
```
117+
118+
* If you want to use the name normalization of Prometheus metrics, you don’t need to do anything. We highly recommend that you verify that queries reference the normalized metric names.

‎src/docs/getting-started/prometheus-remote-write-exporter.mdx

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,24 @@ Regardless of the method of deployment, the ADOT Collector must have access to o
125125
extension depends on the AWS Go SDK and uses it to fetch credentials and authenticate. You must ensure that these credentials have remote writing
126126
permissions to AMP (`aps:RemoteWrite`).
127127

128+
### Name normalization
129+
130+
Starting with ADOT collector v0.35.0, this component will normalize metric names to follow [Prometheus metric naming best practices](https://prometheus.io/docs/practices/naming/). You can control this behavior
131+
through the parameter `add_metric_suffixes`. If this parameter is set to false, no name normalization will happen.
132+
133+
Example:
134+
```yaml lineNumbers=true
135+
prometheusremotewrite:
136+
endpoint: http://example.com
137+
add_metric_suffixes: false # <-- Disable normalization
138+
resource_to_telemetry_conversion:
139+
enabled: true
140+
auth:
141+
authenticator: sigv4auth
142+
```
143+
144+
For more details, please refer to our [migration guide](/docs/migrating-to-collector-v0.35.0).
145+
128146
<SectionSeparator />
129147
130148
## Conclusion

0 commit comments

Comments
 (0)