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 2 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
248 changes: 185 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,64 @@ runnable example.

## Enable OTLP Exporter for all signals

Content coming soon.
A cross-cutting extension was added in v1.8.0 to simplify registration of the
OTLP exporter for all signals (logs, metrics, and tracing).

> [!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.
Calls to `WithLogging`, `WithTracing`, and/or `WithLogging` are NOT required
Copy link
Contributor

@utpilla utpilla Mar 14, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sounds a little confusing. We start off saying calls to the "With" extension methods are not required and then go on to say however only the telemetry enabled using "With" extension methods would be exported.

Maybe update this to something like:

When calling UseOtlpExporter method, you don't need to separately call AddOtlpExporter method for WithLogging, WithTracing, and/or WithMetrics.

Copy link
Member Author

@CodeBlanch CodeBlanch Mar 15, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is kind of tricky. The docs we have that I could find seem to all show "Sdk.Create*" style which really doesn't help for this cross-cutting extension using the hosting style. I decided to show some real examples of how to do it. LMK what you think.

Copy link
Member

@vishweshbankwar vishweshbankwar Mar 15, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WithLogging - This is not a stable way of configuring logging today so I think we should not mention it.

To keep things simple, what do you guys think about something like this.

Using UseOtlpExporter automatically enables the OTLP exporter for logs, metrics, and traces. 
For additional sdk configuration, like adding meters to the MeterProvider, 
incorporating sources to the TracerProvider, or 
configuring resources for all three types of signals, additional setup will required. 
For more information, refer to the details below. (Followed by what we have below)

Copy link
Member Author

@CodeBlanch CodeBlanch Mar 15, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed the mention of the "With" calls and simplified it down to just...

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

when using `UseOtlpExporter` however only telemetry which has been enabled
(typically via `AddSource` inside of `WithTracing` or `AddMeter` inside of
`WithMetrics`) will be exported.

* 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 +334,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 +457,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 ecountered
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