elastic / elastic/docs-content

[Website]: Confusing/oversimplified comment about Tail Based sampling and EDOT

Open
#7,400 3 comments 2 reactions 0 assignees View on GitHub
documentation source:web Team:Ingest Team:SKI triaged
Dominant language
No language data
Stars
47
Forks
261
Avg merge
3d 12h
Merged PRs (30d)
116

Description

### Before you submit

- [x] This issue is about a documentation page, flow, or piece of content.

### Type of issue

Inaccurate

### What documentation page or section is affected

https://www.elastic.co/docs/reference/opentelemetry/compatibility/limitations

### What happened?

Clarify the TBS conundrum with APM

## Current situation

> [When to use the classic Elastic Stack ingestion components instead of EDOT](https://www.elastic.co/docs/reference/opentelemetry/compatibility/limitations#when-to-use-the-classic-elastic-stack-ingestion-components-instead-of-edot)
> ...
> Tail-based sampling (TBS):
> If you need the full tail-based sampling capabilities of APM Server, use APM Server with an Elasticsearch output. EDOT does not provide managed TBS. You can run TBS in a self-managed EDOT Collector or any contrib OTel Collector and ingest the sampled traces into Elastic with some caveats - refer to [Tail-based sampling limitations](https://www.elastic.co/docs/reference/opentelemetry/compatibility/limitations#tail-based-sampling-tbs) for more information.

This statement is confusing. Within the section "When to use the classic Elastic Stack ingestion components instead of EDOT", we recommend to use APM Server if TBS is needed.

But then we follow with a suggestion to use TBS on a self-managed EDOT Collector, linking to https://www.elastic.co/docs/reference/opentelemetry/compatibility/limitations#tail-based-sampling-tbs which again recommends to use APM Server with TBS instead of EDOT, but then hinting to the fact TBS is possible with EDOT Collectors using the `tailsamplingprocessor` (but the tutorial/doc is not linked).

Using the search in the docs for `tailsamplingprocessor`, we can find an actual recipe at https://www.elastic.co/docs/reference/edot-collector/config/configure-tracing-collection#tail-based-sampling - and the page [here](https://www.elastic.co/docs/solutions/observability/apm/opentelemetry/limitations#:~:text=Using%20the%20tailsamplingprocessor%20in%20the%20OpenTelemetry%20Collector%20comes,and%20count%20metrics%20are%20likely%20to%20be%20inaccurate.) really highlights the limitations and caveats in detail.

## Zooming out

As a user, I am confused on what are my options as I get mixed signals on what should I use.

If I am using OTel/EDOT and I want TBS:
- We recommend to use APM Server, but actually this is way more complex than just switching a piece of the ingestion chain.
- EDOT SDKs are NOT tested against APM Server/Integration and not supported as per our own docs
- Switching or using APM Server/Integration implies a translation to ECS which is not mentioned at all but it is a huge difference (especially if the user already started creating dashboards or alerts based on OTel native)
- We mention the possibility to use TBS on EDOT/OTel Collector. We provide a recipe (with `preview` maturity)

Side note: the recommendations can be misinterpreted and might end up having users with EDOT Collector to ship to APM Server just to implement TBS, but with the "Side effect" of getting data translated to ECS.

FYI @wnstn, @cpipilas @hegerchr

### Additional info

_No response_

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the compatibility/limitations page, especially the sections on when to use classic ingestion components and Tail-based sampling limitations. Compare their recommendations with the EDOT Collector tracing collection recipe and its documented caveats. Done means the TBS options and trade-offs are consistent, with the relevant recipe and limitations clearly linked.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, observability-sre
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.