Skip to content
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

Doc tweaks for Exemplars #4273

Merged
merged 2 commits into from
Mar 6, 2023
Merged

Doc tweaks for Exemplars #4273

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
19e593f
Doc tweaks for Exemplars
cijothomas Mar 6, 2023
ca2ceb8
Update docs/metrics/customizing-the-sdk/README.md
cijothomas Mar 6, 2023
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
46 changes: 37 additions & 9 deletions docs/metrics/customizing-the-sdk/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -411,6 +411,19 @@ context, if any. It also provides "Filtered Tags", which are attributes (Tags)
that are [dropped by a view](#select-specific-tags). Exemplars are an opt-in
feature, and allow customization via ExemplarFilter and ExemplarReservoir.

Exemplar collection in OpenTelemetry .NET is done automatically (once Exemplar
feature itself is enabled on `MeterProvider`). There is no separate API
to report exemplar data. If an app is already using existing Metrics API
(manually or via instrumentation libraries), then they would require no
instrumentation change to collect exemplars.
cijothomas marked this conversation as resolved.
Show resolved Hide resolved

While the SDK is capable of producing exemplars automatically, the exporters
(and the backends) must also support them in order to be useful. OTLP Metric
Copy link
Member

Choose a reason for hiding this comment

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

consider adding a link to the OTLP exporter

Exporter has support for this today, and this [end-to-end
tutorial](../exemplars/README.md) demonstrates how to use exemplars to achieve
correlation from metrics to traces, which is one of the primary use cases for
exemplars.

#### ExemplarFilter

`ExemplarFilter` determines which measurements are eligible to become an
Expand All @@ -423,7 +436,8 @@ OpenTelemetry SDK comes with the following Filters:

* `AlwaysOnExemplarFilter` - makes all measurements eligible for being an Exemplar.
* `AlwaysOffExemplarFilter` - makes no measurements eligible for being an
Exemplar. Use this to turn-off Exemplar feature.
Exemplar. Using this is as good as turning off Exemplar feature, and is the current
default.
* `TraceBasedExemplarFilter` - makes those measurements eligible for being an
Exemplar, which are recorded in the context of a sampled parent `Activity`
(span).
Expand All @@ -444,8 +458,11 @@ using var meterProvider = Sdk.CreateMeterProviderBuilder()
```

> **Note**
> As of today, there is no separate toggle for enable/disable Exemplar
feature. It can be turned off by using `AlwaysOffExemplarFilter`.
> As of today, there is no separate toggle for enable/disable Exemplar feature.
Exemplars can be disabled by setting filter as `AlwaysOffExemplarFilter`, which
is also the default (i.e Exemplar feature is disabled by default). Users can
enable the feature by setting filter to anything other than
`AlwaysOffExemplarFilter`. For example: `.SetExemplarFilter(new TraceBasedExemplarFilter())`.

If the built-in `ExemplarFilter`s are not meeting the needs, one may author
custom `ExemplarFilter` as shown
Expand All @@ -459,13 +476,24 @@ much impact can `ExemplarFilter` have on performance.
#### ExemplarReservoir

`ExemplarReservoir` receives the measurements sampled in by the `ExemplarFilter`
and is responsible for storing Exemplars.
`AlignedHistogramBucketExemplarReservoir` is the default reservoir used for
Histograms with buckets, and it stores one exemplar per histogram bucket. The
exemplar stored is the last measurement recorded - i.e. any new measurement
overwrites the previous one.
and is responsible for storing Exemplars. `ExemplarReservoir` ultimately decides
which measurements get stored as exemplars. The following are the default
reservoirs:

* `AlignedHistogramBucketExemplarReservoir` is the default reservoir used for
Histograms with buckets, and it stores at most one exemplar per histogram
bucket. The exemplar stored is the last measurement recorded - i.e. any new
measurement overwrites the previous one in that bucket.

`SimpleExemplarReservoir` is the default reservoir used for all metrics except
Histograms with buckets. It has a fixed reservoir pool, and implements the
equivalent of [naive
reservoir](https://en.wikipedia.org/wiki/Reservoir_sampling). The reservoir pool
size (currently defaulting to 10) determines the maximum number of exemplars
stored.

Currently there is no ability to change the Reservoir used.
> **Note**
> Currently there is no ability to change or configure Reservoir.

### Instrumentation

Expand Down
8 changes: 8 additions & 0 deletions src/OpenTelemetry.Exporter.Prometheus.AspNetCore/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,14 @@ An [OpenTelemetry Prometheus exporter](https://github.com/open-telemetry/opentel
for configuring an ASP.NET Core application with an endpoint for Prometheus
to scrape.

> **Note**
> This exporter does not support [OpenMetrics
format](https://github.com/OpenObservability/OpenMetrics), and consequently,
does not support Exemplars. For using Exemplars, use the [OTLP
Exporter](../OpenTelemetry.Exporter.OpenTelemetryProtocol/README.md) and use a
component like OTel Collector to expose metrics (with exemplars) to Prometheus.
This [tutorial](../../docs/metrics/exemplars/README.md) shows one way how to do that.

## Prerequisite

* [Get Prometheus](https://prometheus.io/docs/introduction/first_steps/)
Expand Down