Hi @carsonip !

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

Thanks!

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.

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.

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

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!

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

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.

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!

👋 @theletterf this is the issue I picked up this week, but I was waiting on a resolution in elastic/docs-content#985 before taking any action.

As agreed with @AlexanderWert, the changes should happen in the https://github.com/elastic/opentelemetry repo for now.

As agreed with @AlexanderWert, the changes should happen in the https://github.com/elastic/opentelemetry repo for now.

Just to confirm, in your discussion, was it clear that this piece of documentation is only relevant to apm server and MIS ingest path, and that it is not relevant to EDOT?

Oh, since I joined (calculates) not even six days ago, probably not, he he.

If it doesn't apply to EDOT, I'mm all for going forward with an edit here or in the new v3 docs. Would gladly get more context in a call.

If it doesn't apply to EDOT, I'mm all for going forward with an edit here or in the new v3 docs. Would gladly get more context in a call.

As elastic/docs-content#985 goes in the direction of removing mentions (including limitations etc) of OTel in Elastic Observability, I wonder if we still want to document this limitation of APM Server and MIS around OTel resource attributes at all. Let's have a wider internal sync on this topic.

Summary of the sync - see elastic/observability-docs#4843 . We can press forward with this documentation task in docs-content

Opening a PR in docs-content using the docs provided by @harshithsaiv.

@colleenmcginnis Do we need to backport (is that the right term?) this to 8.x?

Do we need to backport (is that the right term?) this to 8.x?

The documented table applies to 8.x, but 8.x are documented in observability-docs repo, making backporting a bit more troublesome. It is up to the docs team to decide whether it is worth the trouble.