Skip to content

Commit 1ce5d54

Browse files
BeverlyJaneJsongy23tiffany76
authored
Update internal-telemetry.md (open-telemetry#6799)
Signed-off-by: tiffany76 <[email protected]> Co-authored-by: Yang Song <[email protected]> Co-authored-by: Tiffany Hrabusa <[email protected]>
1 parent 690b2eb commit 1ce5d54

File tree

2 files changed

+78
-33
lines changed

2 files changed

+78
-33
lines changed

‎content/en/docs/collector/internal-telemetry.md‎

Lines changed: 70 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -220,14 +220,15 @@ The Collector emits internal metrics for at least the following values:
220220

221221
A more detailed list is available in the following sections.
222222

223-
### Lists of internal metrics
223+
### Metric names
224224

225-
The following tables group each internal metric by level of verbosity: `basic`,
226-
`normal`, and `detailed`. Each metric is identified by name and description and
227-
categorized by instrumentation type.
225+
This section explains special naming conventions applied to some internal
226+
metrics.
228227

229-
{{% alert title="Note" %}} As of Collector v0.106.1, internal metric names are
230-
handled differently based on their source:
228+
#### `otelcol_` prefix
229+
230+
As of Collector v0.106.1, internal metric names are handled differently based on
231+
their source:
231232

232233
- Metrics generated from Collector components are prefixed with `otelcol_`.
233234
- Metrics generated from instrumentation libraries do not use the `otelcol_`
@@ -236,7 +237,45 @@ handled differently based on their source:
236237
For Collector versions prior to v0.106.1, all internal metrics emitted using the
237238
Prometheus exporter, regardless of their origin, are prefixed with `otelcol_`.
238239
This includes metrics from both Collector components and instrumentation
239-
libraries. {{% /alert %}}
240+
libraries.
241+
242+
#### `_total` suffix
243+
244+
By default and unique to Prometheus, the Prometheus exporter adds a `_total`
245+
suffix to summation metrics to follow Prometheus naming conventions, such as
246+
`otelcol_exporter_send_failed_spans_total`. This behavior can be disabled by
247+
setting `without_type_suffix: false` in the Prometheus exporter's configuration.
248+
249+
If you leave out `service::telemetry::metrics::readers` in the Collector
250+
configuration, the default Prometheus exporter set up by the Collector already
251+
has `without_type_suffix` set to `false`. However, if you customize the readers
252+
and add a Prometheus exporter manually, you must set that option to return to
253+
the "raw" metric name. For more information, see the
254+
[Collector v1.25.0/v0.119.0 release notes](https://github.com/codeboten/opentelemetry-collector/blob/313167505b44e5dc9a29c0b9242cc4547db11ec3/CHANGELOG.md#v1250v01190).
255+
256+
Internal metrics exported through OTLP do not have this behavior. The
257+
[internal metrics](#lists-of-internal-metrics) on this page are listed in OTLP
258+
format, such as `otelcol_exporter_send_failed_spans`.
259+
260+
#### Dots (`.`) v. underscores (`_`)
261+
262+
`http*` and `rpc*` metrics come from instrumentation libraries. Their original
263+
names used dots (`.`). Prior to Collector v0.120.0, internal metrics exposed
264+
with Prometheus changed dots (`.`) to underscores (`_`) to match Prometheus
265+
naming conventions, resulting in metric names that looked like
266+
`rpc_server_duration`.
267+
268+
Versions 0.120.0 and later of the Collector use Prometheus 3.0 scrapers, so the
269+
original `http*` and `rpc*` metric names with dots are preserved. The
270+
[internal metrics](#lists-of-internal-metrics) on this page are listed in their
271+
original form, such as`rpc.server.duration`. For more information, see the
272+
[Collector v0.120.0 release notes](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/CHANGELOG.md#v01200).
273+
274+
### Lists of internal metrics
275+
276+
The following tables group each internal metric by level of verbosity: `basic`,
277+
`normal`, and `detailed`. Each metric is identified by name and description and
278+
categorized by instrumentation type.
240279

241280
{{< comment >}}
242281

@@ -311,40 +350,38 @@ its introduction. Note however that these metrics were inadvertently reverted to
311350

312351
| Metric name | Description | Type |
313352
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------- |
314-
| `http_client_active_requests` | Number of active HTTP client requests. | Counter |
315-
| `http_client_connection_duration` | Measures the duration of the successfully established outbound HTTP connections. | Histogram |
316-
| `http_client_open_connections` | Number of outbound HTTP connections that are active or idle on the client. | Counter |
317-
| `http_client_request_size` | Measures the size of HTTP client request bodies. | Counter |
318-
| `http_client_duration` | Measures the duration of HTTP client requests. | Histogram |
319-
| `http_client_response_size` | Measures the size of HTTP client response bodies. | Counter |
320-
| `http_server_active_requests` | Number of active HTTP server requests. | Counter |
321-
| `http_server_request_size` | Measures the size of HTTP server request bodies. | Counter |
322-
| `http_server_duration` | Measures the duration of HTTP server requests. | Histogram |
323-
| `http_server_response_size` | Measures the size of HTTP server response bodies. | Counter |
353+
| `http.client.active_requests` | Number of active HTTP client requests. | Counter |
354+
| `http.client.connection.duration` | Measures the duration of the successfully established outbound HTTP connections. | Histogram |
355+
| `http.client.open_connections` | Number of outbound HTTP connections that are active or idle on the client. | Counter |
356+
| `http.client.request.size` | Measures the size of HTTP client request bodies. | Counter |
357+
| `http.client.duration` | Measures the duration of HTTP client requests. | Histogram |
358+
| `http.client.response.size` | Measures the size of HTTP client response bodies. | Counter |
359+
| `http.server.active_requests` | Number of active HTTP server requests. | Counter |
360+
| `http.server.request.size` | Measures the size of HTTP server request bodies. | Counter |
361+
| `http.server.duration` | Measures the duration of HTTP server requests. | Histogram |
362+
| `http.server.response.size` | Measures the size of HTTP server response bodies. | Counter |
324363
| `otelcol_processor_batch_batch_`<br>`send_size_bytes` | Number of bytes in the batch that was sent. | Histogram |
325-
| `rpc_client_duration` | Measures the duration of outbound RPC. | Histogram |
326-
| `rpc_client_request_size` | Measures the size of RPC request messages (uncompressed). | Histogram |
327-
| `rpc_client_requests_per_rpc` | Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs. | Histogram |
328-
| `rpc_client_response_size` | Measures the size of RPC response messages (uncompressed). | Histogram |
329-
| `rpc_client_responses_per_rpc` | Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. | Histogram |
330-
| `rpc_server_duration` | Measures the duration of inbound RPC. | Histogram |
331-
| `rpc_server_request_size` | Measures the size of RPC request messages (uncompressed). | Histogram |
332-
| `rpc_server_requests_per_rpc` | Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs. | Histogram |
333-
| `rpc_server_response_size` | Measures the size of RPC response messages (uncompressed). | Histogram |
334-
| `rpc_server_responses_per_rpc` | Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. | Histogram |
335-
336-
{{% alert title="Note" %}} The `http_` and `rpc_` metrics come from
337-
instrumentation libraries. Their original names use dots (`.`), but when
338-
exposing internal metrics with Prometheus, they are translated to use
339-
underscores (`_`) to match Prometheus' naming constraints. These metrics are not
364+
| `rpc.client.duration` | Measures the duration of outbound RPC. | Histogram |
365+
| `rpc.client.request.size` | Measures the size of RPC request messages (uncompressed). | Histogram |
366+
| `rpc.client.requests_per_rpc` | Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs. | Histogram |
367+
| `rpc.client.response.size` | Measures the size of RPC response messages (uncompressed). | Histogram |
368+
| `rpc.client.responses_per_rpc` | Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. | Histogram |
369+
| `rpc.server.duration` | Measures the duration of inbound RPC. | Histogram |
370+
| `rpc.server.request.size` | Measures the size of RPC request messages (uncompressed). | Histogram |
371+
| `rpc.server.requests_per_rpc` | Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs. | Histogram |
372+
| `rpc.server.response.size` | Measures the size of RPC response messages (uncompressed). | Histogram |
373+
| `rpc.server.responses_per_rpc` | Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. | Histogram |
374+
375+
{{% alert title="Note" color="info" %}} The `http*` and `rpc*` metrics are not
340376
covered by the maturity levels below since they are not under the Collector SIG
341377
control.
342378

343379
The `otelcol_processor_batch_` metrics are unique to the `batchprocessor`.
344380

345381
The `otelcol_receiver_`, `otelcol_scraper_`, `otelcol_processor_`, and
346382
`otelcol_exporter_` metrics come from their respective `helper` packages. As
347-
such, some components not using those packages may not emit them. {{% /alert %}}
383+
such, some components not using those packages might not emit them.
384+
{{% /alert %}}
348385

349386
### Events observable with internal logs
350387

‎static/refcache.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3767,6 +3767,10 @@
37673767
"StatusCode": 206,
37683768
"LastSeen": "2025-01-30T14:41:51.138475-05:00"
37693769
},
3770+
"https://github.com/codeboten/opentelemetry-collector/blob/313167505b44e5dc9a29c0b9242cc4547db11ec3/CHANGELOG.md#v1250v01190": {
3771+
"StatusCode": 206,
3772+
"LastSeen": "2025-06-18T16:37:37.617753182-07:00"
3773+
},
37703774
"https://github.com/codefromthecrypt": {
37713775
"StatusCode": 200,
37723776
"LastSeen": "2024-11-18T23:18:18.05798173Z"
@@ -5795,6 +5799,10 @@
57955799
"StatusCode": 206,
57965800
"LastSeen": "2025-01-16T14:34:12.970839-05:00"
57975801
},
5802+
"https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/CHANGELOG.md#v01200": {
5803+
"StatusCode": 206,
5804+
"LastSeen": "2025-06-18T16:37:40.740047715-07:00"
5805+
},
57985806
"https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/README.md": {
57995807
"StatusCode": 206,
58005808
"LastSeen": "2025-01-16T14:33:59.421324-05:00"

0 commit comments

Comments
 (0)