docs: describe how OTel resource attributes are translated and stored in labels

[carsonip]

There are no docs describing how only a subset of OTel resource attributes are translated to ECS, and how the rest are converted, e.g. replacing . with _, and stored under labels.*. These pages are good candidates to describe this limitation.

• https://www.elastic.co/guide/en/observability/current/apm-open-telemetry-resource-attributes.html
• https://www.elastic.co/guide/en/observability/current/apm-open-telemetry-known-limitations.html

[harshithsaiv]

Hi @carsonip !

I would love to contribute to this. Can I give this a try? If possible, could you assign it to me?

Thanks!

[carsonip]

Thanks @harshithsaiv ! The docs are located in https://github.com/elastic/observability-docs . Let's proceed without adding an assignee to this issue first and let me know if you need any help.

[harshithsaiv]

Hi @carsonip Could you please provide the exact list of OTel resource attributes that are translated to ECS fields? This will help ensure the documentation is accurate and comprehensive.

Or I can just generalize it like this

For example:

• deployment.environment is translated to service.environment in ECS.
• Other attributes like custom.attribute are converted to labels.custom_attribute.

[carsonip]

Hey @harshithsaiv , the otlp translation logic is in https://github.com/elastic/apm-data/tree/main/input/otlp and watch out for the tricky parts where

• there's different handling for otlp spans that maps to APM span vs APM transaction
• some fields may be translated conditionally (depending on attribute value type)
• labels captures any fields that are not translated

[harshithsaiv]

Hi @carsonip,

I've updated the OpenTelemetry resource attributes documentation to provide more detailed information about how OTel attributes are mapped to ECS fields. These changes address the documentation gap identified in issue #15509.

Key improvements:

• Added clear explanations about how unmapped attributes are stored under labels.* with dots replaced by underscores
• Documented the different handling of OpenTelemetry spans (mapping to either APM transactions or spans based on span kind)
• Added detailed examples showing the conditional attribute translation based on value types
• Included JSON examples to better illustrate the transformation process

I noticed there's an error in the CI workflow about AsciiDoc files being migrated to Markdown. I understand these changes might need to be converted to Markdown format as part of the ongoing migration. Would you be able to advise on the best path forward? Should I:

1. Convert these changes to Markdown format instead?
2. Wait until after the migration is complete?
3. Proceed with this PR with some special handling?

Thank you for your guidance and for reviewing these documentation improvements!

[carsonip]

Thanks for the PR elastic/observability-docs#4834 . I'll either leave some comments on this one, or a new one in markdown format (explained below)

I noticed there's an error in the CI workflow about AsciiDoc files being migrated to Markdown. I understand these changes might need to be converted to Markdown format as part of the ongoing migration. Would you be able to advise on the best path forward? Should I:
Convert these changes to Markdown format instead?
Wait until after the migration is complete?
Proceed with this PR with some special handling?

It was unfortunate timing. The docs have been moved to https://github.com/elastic/docs-content . Therefore, the answer is you should close elastic/observability-docs#4834 and open one in https://github.com/elastic/docs-content

[harshithsaiv]

Thank you for the update, @carsonip. I'll go ahead and close the PR and open a new one in https://github.com/elastic/docs-content.

[carsonip]

hey @harshithsaiv , just checking in to see if you need any help with the new docs repo. The closed PR looks good at a high level and I'm ready to review your new on in elastic/docs-content once it's ready. Thanks!