Skip to content

Add further clarification and align with wording in internal docs - #62

Open
nicklas-dohrn wants to merge 1 commit into
SAP-docs:mainfrom
nicklas-dohrn:docs/span-passthrough-addition
Open

nicklas-dohrn wants to merge 1 commit into
SAP-docs:mainfrom
nicklas-dohrn:docs/span-passthrough-addition

Conversation

@nicklas-dohrn

Copy link
Copy Markdown
Contributor

Just a further improvement/alignment on this documentation to remove some ambiguity.

Comment on lines 32 to +44
> ### Note:
> By default, the trace pipeline assembles complete traces and populates the service map \(`otel-v1-apm-service-map index`\). If you only need raw span data and do not require service map or full trace assembly, you can enable span passthrough mode:
>
> ```
> {
> "ingest_otlp": {
> "enabled": true,
> "span_passthrough": true
> }
> }
> ```
>
> When `span_passthrough` is set to `true`, spans are written to OpenSearch individually as they arrive. The service map is not populated and trace views may show incomplete traces.
> When `span_passthrough` is set to `true`, spans are written to OpenSearch individually as they arrive, without assembling complete traces. This can be useful if you know that root/parent spans will be missing from your telemetry \(e.g., when only a subset of services in a request path emit spans\), so trace assembly cannot succeed anyway. In this case it lowers ingestion latency at the cost of trace completeness. Furthermore, when enabled, the `otel-v1-apm-service-map` index is not populated, so the Service Map view in the Observability plugin of OpenSearch Dashboards will not function and the Trace Analytics view may show orphaned spans rather than complete trace trees.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To avoid duplication I would prefer to reference the span_passthrough parameter description from the configuration-parameter page.

Suggested change
> When `span_passthrough` is set to `true`, spans are written to OpenSearch individually as they arrive, without assembling complete traces. This can be useful if you know that root/parent spans will be missing from your telemetry \(e.g., when only a subset of services in a request path emit spans\), so trace assembly cannot succeed anyway. In this case it lowers ingestion latency at the cost of trace completeness. Furthermore, when enabled, the `otel-v1-apm-service-map` index is not populated, so the Service Map view in the Observability plugin of OpenSearch Dashboards will not function and the Trace Analytics view may show orphaned spans rather than complete trace trees.
> ### Note:
> If you only need raw span data and do not require service map or full trace assembly, you can enable span passthrough mode (see [ingest_otlp configuration parameter](configuration-parameters-1830bca.md#loio1830bca1b060484e9cfabc0e62472e8e__table_zcy_jjx_jzb)):
>
> ```
> {
> "ingest_otlp": {
> "enabled": true,
> "span_passthrough": true
> }
> }
> ```

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants