[exporter/elasticsearch] Change default `mapping::mode` to `otel` #38458

carsonip · 2025-03-07T15:39:39Z

Description

Breaking change: change default mapping::mode config to otel for the best user experience and the most intuitive document structure in Elasticsearch. See README to learn more about otel mapping mode. To retain the old behavior, explicitly set mapping::mode to none.

Should be released together with #38500

Link to tracking issue

Fixes #37241

Documentation

Updated README

carsonip

README under otel mapping mode

data_stream.dataset will always be appended with .otel. It is recommended to use with
*_dynamic_index::enabled: true (e.g. logs_dynamic_index::enabled) to route documents to data stream
${data_stream.type}-${data_stream.dataset}-${data_stream.namespace}

~~TODO: This seems out of place. It is the responsibility of *_dynamic_index.~~ fixed

carsonip · 2025-03-11T14:58:13Z

exporter/elasticsearchexporter/README.md

-`data_stream.dataset` will always be appended with `.otel`. It is recommended to use with
-`*_dynamic_index::enabled: true` (e.g. `logs_dynamic_index::enabled`) to route documents to data stream
-`${data_stream.type}-${data_stream.dataset}-${data_stream.namespace}`.
+`data_stream.dataset` will always be appended with `.otel` if [dynamic data stream routing mode](#elasticsearch-document-routing) is active.


expecting a conflict with #38500 . Can be resolved once either PR is merged.

axw

❤️

andrzej-stencel · 2025-03-12T12:04:43Z

exporter/elasticsearchexporter/README.md

-Requires Elasticsearch 8.12 or above.
+The default and recommended "OTel-native" mapping mode.
+
+Requires Elasticsearch 8.12 or above[^1], works best with Elasticsearch 8.16 or above[^2].


For a user that uses the Elasticsearch exporter with Elasticsearch < 8.12 and the default mapping mode, they will stop seeing their data in Elasticsearch, and start seeing rejection logs in the collector. This is not ideal.

On the other hand, 8.12 is over a year old (January 2024) and the officially supported versions of Elasticsearch are currently 8.16 and 8.17.

I'm on board with this change as it makes new users' experience much better. Also the remediation is easy for affected users: add a configuration flag, as described in the changelog entry.

andrzej-stencel · 2025-03-12T12:06:00Z

exporter/elasticsearchexporter/README.md

 2. Otherwise, check your metrics pipeline setup for misconfiguration that causes an actual violation of the [single writer principle](https://opentelemetry.io/docs/specs/otel/metrics/data-model/#single-writer).
 This means that the same metric with the same dimensions is sent from multiple sources, which is not allowed in the OTel metrics data model.
+
+### flush failed (400) illegal_argument_exception


Awesome, thanks for adding this. It should make it easier for users affected by this change to fix their setup.

JaredTan95 · 2025-03-12T13:20:36Z

exporter/elasticsearchexporter/README.md

+Requires Elasticsearch 8.12 or above[^1], works best with Elasticsearch 8.16 or above[^2].
+
+[^1]: as it uses the undocumented `require_data_stream` bulk API parameter supported from Elasticsearch 8.12
+[^2]: Elasticsearch 8.16 contains a built-in `otel-data` plugin


hi, Is there a link to the relevant introduction?

Here's a link to the initial PR: elastic/elasticsearch#111091

#### Description Breaking change. Overhaul in document routing. New document routing logic: ``` Documents are statically or dynamically routed to the target index / data stream in the following order. The first routing mode that applies will be used. 1. "Static mode": Route to `logs_index` for log records, `metrics_index` for data points and `traces_index` for spans, if these configs are not empty respectively. [^3] 2. "Dynamic - Index attribute mode": Route to index name specified in `elasticsearch.index` attribute (precedence: log record / data point / span attribute > scope attribute > resource attribute) if the attribute exists. [^3] 3. "Dynamic - Data stream routing mode": Route to data stream constructed from `${data_stream.type}-${data_stream.dataset}-${data_stream.namespace}`, where `data_stream.type` is `logs` for log records, `metrics` for data points, and `traces` for spans, and is static. [^3] In a special case with `mapping::mode: bodymap`, `data_stream.type` field (valid values: `logs`, `metrics`) can be dynamically set from attributes. The resulting documents will contain the corresponding `data_stream.*` fields, see restrictions applied to [Data Stream Fields](https://www.elastic.co/guide/en/ecs/current/ecs-data_stream.html). 1. `data_stream.dataset` or `data_stream.namespace` in attributes (precedence: log record / data point / span attribute > scope attribute > resource attribute) 2. Otherwise, if scope name matches regex `/receiver/(\w*receiver)`, `data_stream.dataset` will be capture group #1 3. Otherwise, `data_stream.dataset` falls back to `generic` and `data_stream.namespace` falls back to `default`. ``` ``` In OTel mapping mode (`mapping::mode: otel`), there is special handling in addition to the above document routing rules in [Elasticsearch document routing](#elasticsearch-document-routing). The order to determine the routing mode is the same as [Elasticsearch document routing](#elasticsearch-document-routing). 1. "Static mode": Span events are separate documents routed to `logs_index` if non-empty. 2. "Dynamic - Index attribute mode": Span events are separate documents routed using attribute `elasticsearch.index` (precedence: span event attribute > scope attribute > resource attribute) if the attribute exists. 3. "Dynamic - Data stream routing mode": - For all documents, `data_stream.dataset` will always be appended with `.otel`. - A special case to (3)(1) in [Elasticsearch document routing](#elasticsearch-document-routing), span events are separate documents that have `data_stream.type: logs` and are routed using data stream attributes (precedence: span event attribute > scope attribute > resource attribute) ``` Effective changes: - Deprecate and make `{logs,metrics,traces}_dynamic_index` config no-op - Config validation error on `{logs,metrics,traces}_dynamic_index::enabled` and `{logs,metrics,traces}_index` set at the same time, as users who rely on dynamic index should not set `{logs,metrics,traces}_index`. - Remove `elasticsearch.index.{prefix,suffix}` handling. Replace it with `elasticsearch.index` handling that uses attribute value as index directly. Users rely on the previously supported `elasticsearch.index.prefix` and `elasticsearch.index.suffix` should migrate to a transform processor that sets `elasticsearch.index`. - Fix a bug where receiver-based routing overwrites data_stream.dataset. Should be released together with #38458  #### Link to tracking issue Fixes #38361  #### Testing  #### Documentation  --------- Co-authored-by: Andrzej Stencel <[email protected]>

carsonip added 2 commits March 7, 2025 15:35

[exporter/elasticsearch] Change default mapping mode to otel

39da605

Add changelog

8903e55

github-actions bot added the exporter/elasticsearch label Mar 7, 2025

github-actions bot requested review from JaredTan95 and lahsivjar March 7, 2025 15:40

Update readme

3928bbb

carsonip commented Mar 7, 2025

View reviewed changes

carsonip added 2 commits March 7, 2025 17:11

Explain ES requirement

abc9c08

Rewrite interaction with *_dynamic_index

620bb5a

carsonip mentioned this pull request Mar 11, 2025

[exporter/elasticsearch] Dynamically route documents by default #38500

Merged

carsonip marked this pull request as ready for review March 11, 2025 14:39

carsonip requested a review from a team as a code owner March 11, 2025 14:39

carsonip requested a review from jpkrohling March 11, 2025 14:39

github-actions bot assigned evan-bradley Mar 11, 2025

Update readme to align with new dynamic document routing

42c5a0c

carsonip commented Mar 11, 2025

View reviewed changes

Merge branch 'main' into mapping-mode-default-otel

f4429b5

felixbarny approved these changes Mar 11, 2025

View reviewed changes

axw approved these changes Mar 12, 2025

View reviewed changes

carsonip added 3 commits March 12, 2025 11:58

Add known issue about sending to older than 8.12

a9c0732

Update symptom

6094b00

Mention collector version

0211be9

andrzej-stencel approved these changes Mar 12, 2025

View reviewed changes

andrzej-stencel added the ready to merge Code review completed; ready to merge by maintainers label Mar 12, 2025

Better changelog

0a797ff

songy23 merged commit 1930d76 into open-telemetry:main Mar 12, 2025
171 checks passed

github-actions bot added this to the next release milestone Mar 12, 2025

JaredTan95 reviewed Mar 12, 2025

View reviewed changes

carsonip mentioned this pull request Mar 24, 2025

Issue After Updating to Version 0.122.0 #38849

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[exporter/elasticsearch] Change default `mapping::mode` to `otel` #38458

[exporter/elasticsearch] Change default `mapping::mode` to `otel` #38458

Uh oh!

carsonip commented Mar 7, 2025 •

edited

Loading

Uh oh!

carsonip left a comment •

edited

Loading

Uh oh!

carsonip Mar 11, 2025

Uh oh!

axw left a comment

Uh oh!

andrzej-stencel Mar 12, 2025

Uh oh!

andrzej-stencel Mar 12, 2025

Uh oh!

Uh oh!

JaredTan95 Mar 12, 2025

Uh oh!

felixbarny Mar 12, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

[exporter/elasticsearch] Change default mapping::mode to otel #38458

[exporter/elasticsearch] Change default mapping::mode to otel #38458

Uh oh!

Conversation

carsonip commented Mar 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Link to tracking issue

Documentation

Uh oh!

carsonip left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carsonip Mar 11, 2025

Choose a reason for hiding this comment

Uh oh!

axw left a comment

Choose a reason for hiding this comment

Uh oh!

andrzej-stencel Mar 12, 2025

Choose a reason for hiding this comment

Uh oh!

andrzej-stencel Mar 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JaredTan95 Mar 12, 2025

Choose a reason for hiding this comment

Uh oh!

felixbarny Mar 12, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

[exporter/elasticsearch] Change default `mapping::mode` to `otel` #38458

[exporter/elasticsearch] Change default `mapping::mode` to `otel` #38458

carsonip commented Mar 7, 2025 •

edited

Loading

carsonip left a comment •

edited

Loading