Skip to content

[otlp] Add readme toc and clarify endpoint confusion #5385

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 6 commits into from
Mar 12, 2024
Merged

[otlp] Add readme toc and clarify endpoint confusion #5385

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5bdde2e
organize readme and clarify endpoint confusion
vishweshbankwar Feb 23, 2024
5a24f74
reword
vishweshbankwar Feb 23, 2024
ab30bcb
indent
vishweshbankwar Feb 23, 2024
b12e3e2
fix link
vishweshbankwar Feb 23, 2024
c0a67a8
re-arrange sequence
vishweshbankwar Feb 23, 2024
9b77cf0
Merge branch 'main' into vibankwa/organize-otlp-readme
vishweshbankwar Mar 12, 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
103 changes: 64 additions & 39 deletions src/OpenTelemetry.Exporter.OpenTelemetryProtocol/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,26 @@
[The OTLP (OpenTelemetry Protocol) exporter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md)
implementation.

<!-- markdownlint-disable MD033 -->
<details>
<summary>Table of Contents</summary>

* [Installation](#installation)
* [Enable Log Exporter](#enable-log-exporter)
* [Enable Metric Exporter](#enable-metric-exporter)
* [Enable Trace Exporter](#enable-trace-exporter)
* [Configuration](#configuration)
* [OtlpExporterOptions](#otlpexporteroptions)
* [LogRecordExportProcessorOptions](#logrecordexportprocessoroptions)
* [MetricReaderOptions](#metricreaderoptions)
* [Environment Variables](#environment-variables)
* [Experimental Features](#environment-variables-for-experimental-features)
* [Configure HttpClient](#configure-httpclient)
* [Troubleshooting](#troubleshooting)

</details>
<!-- markdownlint-enable MD033 -->

## Prerequisite

* An endpoint capable of accepting OTLP, like [OpenTelemetry
Expand All @@ -17,45 +37,6 @@ implementation.
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
```

## Enable Trace Exporter

This exporter provides `AddOtlpExporter()` extension method on `TracerProviderBuilder`
to enable exporting of traces. The following snippet adds the Exporter with default
[configuration](#configuration).

```csharp
var tracerProvider = Sdk.CreateTracerProviderBuilder()
// rest of config not shown here.
.AddOtlpExporter()
.Build();
```

See the [`TestOtlpExporter.cs`](../../examples/Console/TestOtlpExporter.cs) for
runnable example.

## Enable Metric Exporter

This exporter provides `AddOtlpExporter()` extension method on `MeterProviderBuilder`
to enable exporting of metrics. The following snippet adds the Exporter with default
[configuration](#configuration).

```csharp
var meterProvider = Sdk.CreateMeterProviderBuilder()
// rest of config not shown here.
.AddOtlpExporter()
.Build();
```

By default, `AddOtlpExporter()` pairs the OTLP MetricExporter with a
[PeriodicExportingMetricReader](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#periodic-exporting-metricreader)
with metric export interval of 60 secs and
[Temporality](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/data-model.md#temporality)
set as `Cumulative`. See
[`TestMetrics.cs`](../../examples/Console/TestMetrics.cs) for example on how to
customize the `MetricReaderOptions` or see the [Environment
Variables](#environment-variables) section below on how to customize using
environment variables.

## Enable Log Exporter

```csharp
Expand Down Expand Up @@ -89,6 +70,45 @@ setting on `OpenTelemetryLoggerOptions`.
> Scope attributes with key set as empty string or `{OriginalFormat}`
are ignored by exporter. Duplicate keys are exported as is.

## Enable Metric Exporter

This exporter provides `AddOtlpExporter()` extension method on `MeterProviderBuilder`
to enable exporting of metrics. The following snippet adds the Exporter with default
[configuration](#configuration).

```csharp
var meterProvider = Sdk.CreateMeterProviderBuilder()
// rest of config not shown here.
.AddOtlpExporter()
.Build();
```

By default, `AddOtlpExporter()` pairs the OTLP MetricExporter with a
[PeriodicExportingMetricReader](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#periodic-exporting-metricreader)
with metric export interval of 60 secs and
[Temporality](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/data-model.md#temporality)
set as `Cumulative`. See
[`TestMetrics.cs`](../../examples/Console/TestMetrics.cs) for example on how to
customize the `MetricReaderOptions` or see the [Environment
Variables](#environment-variables) section below on how to customize using
environment variables.

## Enable Trace Exporter

This exporter provides `AddOtlpExporter()` extension method on `TracerProviderBuilder`
to enable exporting of traces. The following snippet adds the Exporter with default
[configuration](#configuration).

```csharp
var tracerProvider = Sdk.CreateTracerProviderBuilder()
// rest of config not shown here.
.AddOtlpExporter()
.Build();
```

See the [`TestOtlpExporter.cs`](../../examples/Console/TestOtlpExporter.cs) for
runnable example.

## Configuration

You can configure the `OtlpExporter` through `OtlpExporterOptions`
Expand Down Expand Up @@ -169,6 +189,11 @@ appBuilder.Services.AddOptions<OtlpExporterOptions>()
`OtlpExportProtocol.Grpc` and "localhost:4318" for
`OtlpExportProtocol.HttpProtobuf`.

> [!NOTE]
> When using `OtlpExportProtocol.HttpProtobuf`, the full URL MUST be
> provided, including the signal-specific path v1/{signal}. For example, for
> traces, the full URL will look like `http://your-custom-endpoint/v1/traces`.

* `Headers`: Optional headers for the connection.

* `HttpClientFactory`: A factory function called to create the `HttpClient`
Expand Down