Skip to content

[otlp] Update README for UseOtlpExporter & new experimental flag #5452

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 17 commits into from
Mar 21, 2024
Merged

[otlp] Update README for UseOtlpExporter & new experimental flag #5452

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
0c8d633
Update OtlpExporter README for UseOtlpExporter & OTEL_DOTNET_EXPERIME…
CodeBlanch Mar 14, 2024
c4e8ee4
Lint.
CodeBlanch Mar 14, 2024
48d300d
Code review.
CodeBlanch Mar 15, 2024
a71bc61
Lint.
CodeBlanch Mar 15, 2024
841175e
Add metrics config example.
CodeBlanch Mar 15, 2024
31e6f2f
Code review.
CodeBlanch Mar 15, 2024
ba1fac9
Tweaks.
CodeBlanch Mar 15, 2024
d5609a9
Code review.
CodeBlanch Mar 18, 2024
9a35880
Tweak.
CodeBlanch Mar 18, 2024
727012a
Code review and tweaks.
CodeBlanch Mar 19, 2024
b5d88d1
Lint.
CodeBlanch Mar 19, 2024
ae79059
Merge branch 'main' into otlp-exporter-doc-updates
CodeBlanch Mar 19, 2024
b21da4b
Code review.
CodeBlanch Mar 19, 2024
452c40b
Lint.
CodeBlanch Mar 19, 2024
2142ecb
Code review.
CodeBlanch Mar 20, 2024
92ed619
Merge remote-tracking branch 'upstream/main' into otlp-exporter-doc-u…
CodeBlanch Mar 21, 2024
8e2e25a
Code review.
CodeBlanch Mar 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion ...etry.Exporter.OpenTelemetryProtocol/Builder/OpenTelemetryBuilderOtlpExporterExtensions.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ public static class OpenTelemetryBuilderOtlpExporterExtensions
/// tracing.</item>
/// <item>The exporter registered by this method will be added as the last
/// processor in the pipeline established for logging and tracing.</item>
/// <item>This method can only be called once. Subsequent calls will results
/// <item>This method can only be called once. Subsequent calls will result
/// in a <see cref="NotSupportedException"/> being thrown.</item>
/// <item>This method cannot be called in addition to signal-specific
/// <c>AddOtlpExporter</c> methods. If this method is called signal-specific
Expand Down
340 changes: 277 additions & 63 deletions src/OpenTelemetry.Exporter.OpenTelemetryProtocol/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,9 @@ implementation.
* [LogRecordExportProcessorOptions](#logrecordexportprocessoroptions)
* [MetricReaderOptions](#metricreaderoptions)
* [Environment Variables](#environment-variables)
* [Experimental Features](#environment-variables-for-experimental-features)
* [Exporter configuration](#exporter-configuration)
* [Attribute limits](#attribute-limits)
* [Experimental features](#experimental-features)
* [Configure HttpClient](#configure-httpclient)
* [Troubleshooting](#troubleshooting)

Expand Down Expand Up @@ -112,7 +114,156 @@ runnable example.

## Enable OTLP Exporter for all signals

Content coming soon.
Starting with the `1.8.0` version you can use the cross-cutting
`UseOtlpExporter` extension to simplify registration of the OTLP exporter for
all signals (logs, metrics, and traces).

> [!NOTE]
> The cross cutting extension is currently only available when using the
`AddOpenTelemetry` extension in the
[OpenTelemetry.Extensions.Hosting](../OpenTelemetry.Extensions.Hosting/README.md)
package.

```csharp
appBuilder.Services.AddOpenTelemetry()
.UseOtlpExporter();
```

The `UseOtlpExporter` has the following behaviors:

* Calling `UseOtlpExporter` automatically enables logging, metrics, and tracing
however only telemetry which has been enabled will be exported.

There are different mechanisms available to enable telemetry:

* Logging

`ILogger` telemetry is controlled by category filters typically set through
configuration. For details see: [Log
Filtering](../../docs/logs/customizing-the-sdk/README.md#log-filtering) and
[Logging in
.NET](https://docs.microsoft.com/dotnet/core/extensions/logging).

* Metrics

Metrics telemetry is controlled by calling `MeterProviderBuilder.AddMeter`
to listen to
[Meter](https://learn.microsoft.com/dotnet/api/system.diagnostics.meter)s
emitting metrics. Typically instrumentation packages will make this call
automatically.

Examples:

```csharp
appBuilder.Services.AddOpenTelemetry()
.UseOtlpExporter()
.WithMetrics(metrics => metrics
.AddMeter(MyMeter.Name) // Listen to custom telemetry
.AddAspNetCoreInstrumentation() // Use instrumentation to listen to telemetry
);
```

```csharp
appBuilder.Services.ConfigureOpenTelemetryMeterProvider(metrics => metrics
.AddMeter(MyMeter.Name) // Listen to custom telemetry
.AddAspNetCoreInstrumentation() // Use instrumentation to listen to telemetry
);

appBuilder.Services.AddOpenTelemetry()
.UseOtlpExporter();
```

For details see: [Meter](../../docs/metrics/customizing-the-sdk/README.md#meter).

When using `Microsoft.Extensions.Hosting` v8.0.0 or greater (a standard part
of ASP.NET Core) `Meter`s and `Instrument`s can also be enabled using
configuration.

`appSettings.json` metrics configuration example:

```json
{
"Metrics": {
"EnabledMetrics": {
"Microsoft.AspNetCore.*": true,
"System.*": true,
"MyCompany.*": true,
}
}
}
```

For details about the built-in metrics exposed by .NET see: [Built-in
metrics in
.NET](https://learn.microsoft.com/dotnet/core/diagnostics/built-in-metrics).

* Tracing

Trace telemetry is controlled by calling `TracerProviderBuilder.AddSource`
to listen to
[ActivitySource](https://learn.microsoft.com/dotnet/api/system.diagnostics.activitysource)s
emitting traces. Typically instrumentation packages will make this call
automatically.

Examples:

```csharp
appBuilder.Services.AddOpenTelemetry()
.UseOtlpExporter()
.WithTracing(tracing => tracing
.AddSource(MyActivitySource.Name) // Listen to custom telemetry
.AddAspNetCoreInstrumentation() // Use instrumentation to listen to telemetry
);
```

```csharp
appBuilder.Services.ConfigureOpenTelemetryTracerProvider(tracing => tracing
.AddSource(MyActivitySource.Name) // Listen to custom telemetry
.AddAspNetCoreInstrumentation() // Use instrumentation to listen to telemetry
);

appBuilder.Services.AddOpenTelemetry()
.UseOtlpExporter();
```

For details see: [Activity Source](../../docs/trace/customizing-the-sdk/README.md#activity-source).

* The exporter registered by `UseOtlpExporter` will be added as the last
processor in the pipeline established for logging and tracing.

* `UseOtlpExporter` can only be called once. Subsequent calls will result in a
`NotSupportedException` being thrown.

* `UseOtlpExporter` cannot be called in addition to signal-specific
`AddOtlpExporter` methods. If `UseOtlpExporter` is called signal-specific
`AddOtlpExporter` calls will result in a `NotSupportedException` being thrown.

### Configuring signals when using UseOtlpExporter

`UseOtlpExporter` supports the full set of [environment
variables](#environment-variables) listed below including the signal-specific
overrides and users are encouraged to use this mechanism to configure their
exporters.

> [!NOTE]
> In OpenTelemetry .NET environment variable keys are retrieved using
`IConfiguration` which means they may be set using other mechanisms such as
defined in appSettings.json or specified on the command-line.

An `UseOtlpExporter` overload is provided which may be used to set the protocol
and base endpoint but no other options are currently exposed:

```csharp
appBuilder.Services.AddOpenTelemetry()
.UseOtlpExporter(
OtlpExportProtocol.HttpProtobuf,
new Uri("http://otlp_exporter_base_address/"));
```

> [!NOTE]
> When the protocol is set to `OtlpExportProtocol.HttpProtobuf` a
signal-specific path will be appended automatically to the base endpoint when
constructing exporters.

## Configuration

Expand Down Expand Up @@ -275,64 +426,121 @@ appBuilder.Services.Configure<MetricReaderOptions>(

## Environment Variables

The following environment variables can be used to override the default
values of the `OtlpExporterOptions`
(following the [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md)).

| Environment variable | `OtlpExporterOptions` property |
| ------------------------------| --------------------------------------|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `Endpoint` |
| `OTEL_EXPORTER_OTLP_HEADERS` | `Headers` |
| `OTEL_EXPORTER_OTLP_TIMEOUT` | `TimeoutMilliseconds` |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `Protocol` (`grpc` or `http/protobuf`)|

The following environment variables can be used to override the default values
for `BatchExportProcessorOptions` in case of `OtlpTraceExporter` (following the
[OpenTelemetry
specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#batch-span-processor))

| Environment variable | `OtlpExporterOptions.BatchExportProcessorOptions` property |
| ---------------------------------| ------------------------------------------------------------|
| `OTEL_BSP_SCHEDULE_DELAY` | `ScheduledDelayMilliseconds` |
| `OTEL_BSP_EXPORT_TIMEOUT` | `ExporterTimeoutMilliseconds` |
| `OTEL_BSP_MAX_QUEUE_SIZE` | `MaxQueueSize` |
| `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` | `MaxExportBatchSize` |

The following environment variables can be used to override the default values
for `BatchExportProcessorOptions` in case of `OtlpLogExporter` (following the
[OpenTelemetry
specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#batch-logrecord-processor))

| Environment variable | `LogRecordExportProcessorOptions.BatchExportProcessorOptions` property |
| ----------------------------------| ------------------------------------------------------------------------|
| `OTEL_BLRP_SCHEDULE_DELAY` | `ScheduledDelayMilliseconds` |
| `OTEL_BLRP_EXPORT_TIMEOUT` | `ExporterTimeoutMilliseconds` |
| `OTEL_BLRP_MAX_QUEUE_SIZE` | `MaxQueueSize` |
| `OTEL_BLRP_MAX_EXPORT_BATCH_SIZE` | `MaxExportBatchSize` |

The following environment variables can be used to override the default values
of the `PeriodicExportingMetricReaderOptions` (following the [OpenTelemetry
specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.12.0/specification/sdk-environment-variables.md#periodic-exporting-metricreader).

| Environment variable | `PeriodicExportingMetricReaderOptions` property |
| ----------------------------------------------------| ------------------------------------------------|
| `OTEL_METRIC_EXPORT_INTERVAL` | `ExportIntervalMilliseconds` |
| `OTEL_METRIC_EXPORT_TIMEOUT` | `ExportTimeoutMilliseconds` |

| Environment variable | `MetricReaderOptions` property |
| ----------------------------------------------------| ------------------------------------------------|
| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | `PeriodicExportingMetricReaderOptions` |

The following environment variables can be used to override the default
values of the attribute limits
(following the [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.25.0/specification/configuration/sdk-environment-variables.md#attribute-limits)).
### Exporter configuration

The [OpenTelemetry
Specification](https://github.com/open-telemetry/opentelemetry-specification/)
defines environment variables which can be used to configure the [OTLP
exporter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md)
and its associated processor
([logs](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#batch-logrecord-processor)
&
[traces](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#batch-span-processor))
or reader
([metrics](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#periodic-exporting-metricreader)).

* All signals

The following environment variables can be used to override the default
values of the `OtlpExporterOptions`:

| Environment variable | `OtlpExporterOptions` property |
| ------------------------------| --------------------------------------|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `Endpoint` |
| `OTEL_EXPORTER_OTLP_HEADERS` | `Headers` |
| `OTEL_EXPORTER_OTLP_TIMEOUT` | `TimeoutMilliseconds` |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `Protocol` (`grpc` or `http/protobuf`)|

* Logs:

The following environment variables can be used to override the default values
for the batch processor configured for logging:

| Environment variable | `LogRecordExportProcessorOptions.BatchExportProcessorOptions` property |
| ----------------------------------| ------------------------------------------------------------------------|
| `OTEL_BLRP_SCHEDULE_DELAY` | `ScheduledDelayMilliseconds` |
| `OTEL_BLRP_EXPORT_TIMEOUT` | `ExporterTimeoutMilliseconds` |
| `OTEL_BLRP_MAX_QUEUE_SIZE` | `MaxQueueSize` |
| `OTEL_BLRP_MAX_EXPORT_BATCH_SIZE` | `MaxExportBatchSize` |

The following environment variables can be used to override the default values
of the `OtlpExporterOptions` used for logging when using the [UseOtlpExporter
extension](#enable-otlp-exporter-for-all-signals):

| Environment variable | `OtlpExporterOptions` property | UseOtlpExporter | AddOtlpExporter |
| --------------------------------------| --------------------------------------|-----------------|-----------------|
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | `Endpoint` | Supported | Not supported |
| `OTEL_EXPORTER_OTLP_LOGS_HEADERS` | `Headers` | Supported | Not supported |
| `OTEL_EXPORTER_OTLP_LOGS_TIMEOUT` | `TimeoutMilliseconds` | Supported | Not supported |
| `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` | `Protocol` (`grpc` or `http/protobuf`)| Supported | Not supported |

* Metrics:

The following environment variables can be used to override the default value
of the `TemporalityPreference` setting for the reader configured for metrics
when using OTLP exporter:

| Environment variable | `MetricReaderOptions` property |
| ----------------------------------------------------| ------------------------------------------------|
| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | `TemporalityPreference` |

The following environment variables can be used to override the default values
of the periodic exporting metric reader configured for metrics:

| Environment variable | `PeriodicExportingMetricReaderOptions` property |
| ----------------------------------------------------| ------------------------------------------------|
| `OTEL_METRIC_EXPORT_INTERVAL` | `ExportIntervalMilliseconds` |
| `OTEL_METRIC_EXPORT_TIMEOUT` | `ExportTimeoutMilliseconds` |

The following environment variables can be used to override the default values
of the `OtlpExporterOptions` used for metrics when using the [UseOtlpExporter
extension](#enable-otlp-exporter-for-all-signals):

| Environment variable | `OtlpExporterOptions` property | UseOtlpExporter | AddOtlpExporter |
| --------------------------------------| --------------------------------------|-----------------|-----------------|
| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | `Endpoint` | Supported | Not supported |
| `OTEL_EXPORTER_OTLP_METRICS_HEADERS` | `Headers` | Supported | Not supported |
| `OTEL_EXPORTER_OTLP_METRICS_TIMEOUT` | `TimeoutMilliseconds` | Supported | Not supported |
| `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` | `Protocol` (`grpc` or `http/protobuf`)| Supported | Not supported |

* Tracing:

The following environment variables can be used to override the default values
for the batch processor configured for tracing:

| Environment variable | `OtlpExporterOptions.BatchExportProcessorOptions` property |
| ---------------------------------| ------------------------------------------------------------|
| `OTEL_BSP_SCHEDULE_DELAY` | `ScheduledDelayMilliseconds` |
| `OTEL_BSP_EXPORT_TIMEOUT` | `ExporterTimeoutMilliseconds` |
| `OTEL_BSP_MAX_QUEUE_SIZE` | `MaxQueueSize` |
| `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` | `MaxExportBatchSize` |

The following environment variables can be used to override the default values
of the `OtlpExporterOptions` used for tracing when using the [UseOtlpExporter
extension](#enable-otlp-exporter-for-all-signals):

| Environment variable | `OtlpExporterOptions` property | UseOtlpExporter | AddOtlpExporter |
| --------------------------------------| --------------------------------------|-----------------|-----------------|
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | `Endpoint` | Supported | Not supported |
| `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | `Headers` | Supported | Not supported |
| `OTEL_EXPORTER_OTLP_TRACES_TIMEOUT` | `TimeoutMilliseconds` | Supported | Not supported |
| `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` | `Protocol` (`grpc` or `http/protobuf`)| Supported | Not supported |

### Attribute limits

The [OpenTelemetry
Specification](https://github.com/open-telemetry/opentelemetry-specification/)
defines environment variables which can be used to configure [attribute
limits](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#attribute-limits).

The following environment variables can be used to configure default attribute
limits:

* `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`
* `OTEL_ATTRIBUTE_COUNT_LIMIT`

The following environment variables can be used to override the default
values of the span limits
(following the [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.25.0/specification/configuration/sdk-environment-variables.md#span-limits)).
The following environment variables can be used to configure span limits used
for tracing:

* `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT`
* `OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT`
Expand All @@ -341,21 +549,27 @@ values of the span limits
* `OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT`
* `OTEL_LINK_ATTRIBUTE_COUNT_LIMIT`

The following environment variables can be used to override the default
values of the log record limits
(following the [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.25.0/specification/configuration/sdk-environment-variables.md#logrecord-limits)).
The following environment variables can be used to configure log record limits
used for logging:

* `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT`
* `OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT`

## Environment Variables for Experimental Features
### Experimental features

### All signals

* `OTEL_DOTNET_EXPERIMENTAL_OTLP_ENABLE_INMEMORY_RETRY`

When set to `true`, it enables in-memory retry for transient errors
encountered sending telemetry.

### Otlp Log Exporter
### Logs

* `OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES`

When set to `true`, it enables export of `LogRecord.EventId.Id` as
`logrecord.event.id` and `LogRecord.EventId.Name` to `logrecord.event.name`.
When set to `true`, it enables export of `LogRecord.EventId.Id` as
`logrecord.event.id` and `LogRecord.EventId.Name` to `logrecord.event.name`.

## Configure HttpClient

Expand Down