Add custom metrics quickstart guide for EDOT #4219
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,158 @@ | ||
| --- | ||
| navigation_title: Ingest custom metrics with EDOT | ||
| description: Learn how to send custom metrics to Elastic using EDOT and OTLP. This lightweight quickstart covers the minimal setup to ingest and validate metrics in Elastic Observability. | ||
| applies_to: | ||
| stack: | ||
| serverless: | ||
| observability: | ||
| product: | ||
| edot_collector: ga | ||
| products: | ||
| - id: cloud-serverless | ||
| - id: cloud-hosted | ||
| - id: observability | ||
| - id: edot-collector | ||
| --- | ||
|
|
||
| # Quickstart: Ingest custom metrics with EDOT | ||
|
|
||
| Use this quickstart to send custom metrics to Elastic using the Elastic Distribution of the OpenTelemetry Collector (EDOT). | ||
|
|
||
| You’ll install a lightweight EDOT Collector, configure a minimal Open Telemetry Protocol (OTLP) metrics pipeline, and verify the data in {{product.observability}}. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - An Elastic deployment ({{serverless-short}}, {{ech}}, or self-managed) | ||
| - An {{observability}} project {{kib}} instance | ||
| - Permissions to create API keys | ||
| - A system to run the EDOT Collector (Docker, host, or VM) | ||
| - Optional: An application that emits OpenTelemetry metrics | ||
|
|
||
| :::::{stepper} | ||
|
|
||
| ::::{step} Create an Elastic API key | ||
|
|
||
| In your {{product.observability}} deployment: | ||
|
|
||
| 1. Go to **{{manage-app}}** > **{{stack-manage-app}}** > **API keys**. | ||
| 2. Create a new API key and copy the value. | ||
| 3. Note your deployment's OTLP ingest endpoint. | ||
| :::: | ||
|
|
||
| ::::{step} Run the EDOT Collector with a minimal metrics pipeline | ||
|
|
||
| Update the `collector-config.yaml` file with the following Collector configuration to receive OTLP metrics and export them to Elastic: | ||
|
|
||
| ```yaml | ||
| receivers: | ||
| otlp: | ||
| protocols: | ||
| http: | ||
| grpc: | ||
|
|
||
| processors: | ||
| batch: {} | ||
|
|
||
| exporters: | ||
| otlphttp: | ||
| endpoint: "<OTLP_ENDPOINT>" | ||
| headers: | ||
| Authorization: "ApiKey <YOUR_API_KEY>" | ||
|
|
||
| service: | ||
| pipelines: | ||
| metrics: | ||
| receivers: [otlp] | ||
| processors: [batch] | ||
| exporters: [otlphttp] | ||
| ``` | ||
|
|
||
| Run the configuration, for example with Docker: | ||
|
|
||
| ```bash | ||
| docker run --rm \ | ||
| -v $(pwd)/collector-config.yaml:/etc/otel/config.yaml \ | ||
| -p 4317:4317 -p 4318:4318 \ | ||
| docker.elastic.co/observability/otel-collector:latest | ||
| ``` | ||
| :::: | ||
|
|
||
| ::::{step} Optional: Port conflict handling | ||
|
|
||
| If you encounter a port conflict error like: | ||
|
|
||
| ```bash | ||
| bind: address already in use | ||
| ``` | ||
|
|
||
| Add the following to the `service` section: | ||
|
|
||
| ```yaml | ||
| service: | ||
| telemetry: | ||
| metrics: | ||
| address: localhost:8889 # Using different port if 8888 is already in use | ||
| ``` | ||
|
|
||
| You can also verify if the Collector is listening on the correct ports: | ||
|
|
||
| ```bash | ||
| lsof -i :4318 -i :4317 | ||
| ``` | ||
| :::: | ||
|
|
||
| ::::{step} Send a custom metric | ||
|
|
||
| In this Python example, you use an application that emits OTLP metrics. For other languages, refer to the [contrib OpenTelemetry documentation](https://opentelemetry.io/docs/getting-started/dev/). | ||
|
|
||
| ```python | ||
| from opentelemetry import metrics | ||
| from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter | ||
| from opentelemetry.sdk.metrics import MeterProvider | ||
| from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader | ||
|
|
||
| exporter = OTLPMetricExporter(endpoint="http://localhost:4318/v1/metrics") | ||
| reader = PeriodicExportingMetricReader(exporter) | ||
| provider = MeterProvider(metric_readers=[reader]) | ||
| metrics.set_meter_provider(provider) | ||
|
|
||
| meter = metrics.get_meter("custom-app") | ||
|
|
||
| temperature = meter.create_observable_gauge( | ||
| "custom.temperature", | ||
| callbacks=[lambda options: [metrics.Observation(26.7)]], | ||
| ) | ||
|
|
||
| input("Sending metrics periodically... press Enter to stop") | ||
| ``` | ||
| :::: | ||
|
|
||
| ::::{step} Verify metrics in {{product.observability}} | ||
|
|
||
| In {{kib}}: | ||
|
|
||
| 1. Go to **Infrastructure** > **Metrics Explorer**. | ||
| 2. Search for `custom.temperature`. | ||
| 3. Visualize or aggregate the metric data. | ||
| :::: | ||
|
|
||
| ::::: | ||
|
|
||
| ## Explore your metrics | ||
|
|
||
| You've successfully set up a minimal OTLP metrics pipeline with the EDOT Collector. Your custom metrics are flowing into {{product.observability}} and can be visualized in {{kib}}. | ||
|
|
||
| Now you can: | ||
|
|
||
| - Use **Metrics Explorer** to create custom visualizations and dashboards | ||
| - Set up alerts based on your custom metrics | ||
| - Aggregate and analyze metric trends over time | ||
|
|
||
| ## Extend your setup | ||
|
|
||
| You can expand your metrics collection setup in several ways: | ||
|
|
||
| - Add more receivers to collect additional metrics | ||
| - Configure the same Collector to send logs and traces alongside metrics | ||
|
|
||
| To learn more, refer to the [Elastic Distribution of the OpenTelemetry Collector documentation](elastic-agent://reference/edot-collector/index.md). | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Once this is merged, I think we should also link to this guide from https://www.elastic.co/docs/manage-data/data-store/data-streams/tsds-ingest-otlp or https://www.elastic.co/docs/manage-data/data-store/data-streams/quickstart-tsds.
@marciw WDYT?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yes, thanks @felixbarny 🙂
added it to the list in #3179