docs(integration): Add Elasticsearch APM Integration guide #126
Conversation
WalkthroughAdds a new Elasticsearch APM integration MDX documenting OTLP routing via an OpenTelemetry Collector to Elastic APM Server, quick-start steps, collector config, workflow decorator examples, Kibana trace visualization, captured metadata, and production/security considerations; also updates integration listing and catalog card. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro Disabled knowledge base sources:
📒 Files selected for processing (3)
🔇 Additional comments (2)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
openllmetry/integrations/elasticsearch-apm.mdx (2)
35-59: Use environment variable in code example for consistency with Step 2.The Quick Start shows setting
OTEL_EXPORTER_OTLP_ENDPOINTin Step 2 but then hardcodes the endpoint value in Step 3 instead of reading from the environment variable. This creates two conflicting patterns. Refactor to use the already-importedgetenv()to read the endpoint from the environment variable, reinforcing the pattern from Step 2.Traceloop.init( app_name="your-service-name", - api_endpoint="http://localhost:4318" + api_endpoint=getenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4318") )
139-153: Standardize processor ordering: movememory_limiterto the first position.Processor ordering differs between pipelines: trace pipeline (line 142) has
memory_limiterlast, while metrics pipeline (line 147) has it first. Best practice is to placememory_limiterfirst in all pipelines to enforce memory bounds before other processing occurs.pipelines: traces: receivers: [otlp] - processors: [batch, resource, memory_limiter] + processors: [memory_limiter, batch, resource] exporters: [otlp/apm, logging, debug] metrics: receivers: [otlp] processors: [memory_limiter, batch, resource] exporters: [otlp/apm, logging] logs: receivers: [otlp] - processors: [memory_limiter, batch, resource] + processors: [memory_limiter, batch, resource] exporters: [otlp/apm, logging]
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
⛔ Files ignored due to path filters (2)
img/integrations/elasticsearch-apm-trace-details.pngis excluded by!**/*.pngimg/integrations/elasticsearch-apm.pngis excluded by!**/*.png
📒 Files selected for processing (1)
openllmetry/integrations/elasticsearch-apm.mdx(1 hunks)
🔇 Additional comments (4)
openllmetry/integrations/elasticsearch-apm.mdx (4)
175-215: Workflow decorator examples are clear and accurate.The
@workflowand@taskdecorator patterns are correctly shown with proper initialization order and expected trace hierarchy documentation in Kibana. The examples are syntactically correct and pedagogically sound.
227-235: Verify image paths are correct for the documentation site structure.The documentation references images at
/img/integrations/elasticsearch-apm.pngand/img/integrations/elasticsearch-apm-trace-details.png. Ensure these absolute paths exist in your documentation site's public assets directory and match your build configuration.
273-281: Processor name and configuration are correct.The
probabilistic_samplerprocessor withsampling_percentageis valid per OpenTelemetry Collector standards. The example configuration (sampling 10% of traces) is accurate. If sampling is a common production requirement, consider adding it as an optional processor example in the main config section (lines 88-154).
165-173: The documentation is accurate—TRACELOOP_TRACE_CONTENTdefaults totruein the Traceloop SDK, and the warning about disabling it in production is appropriately placed and necessary for security.
| - [Elastic APM Documentation](https://www.elastic.co/guide/en/apm/guide/current/index.html) | ||
| - [OpenTelemetry Collector Configuration](https://opentelemetry.io/docs/collector/configuration/) | ||
| - [Traceloop SDK Configuration](https://www.traceloop.com/docs/openllmetry/configuration) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify external links are accessible
for url in \
"https://www.elastic.co/guide/en/apm/guide/current/index.html" \
"https://opentelemetry.io/docs/collector/configuration/" \
"https://www.traceloop.com/docs/openllmetry/configuration"; do
echo "Checking: $url"
curl -s -o /dev/null -w "HTTP Status: %{http_code}\n" "$url"
doneRepository: traceloop/docs
Length of output: 172
🌐 Web query:
Elastic APM Documentation current URL https://www.elastic.co/guide/en/apm/guide/current/index.html
💡 Result:
The URL you gave (https://www.elastic.co/guide/en/apm/guide/current/index.html) is legacy — the APM guide pages now live under the APM guide index (and, since v8.12, content has moved into the Observability guide). See Elastic’s APM guide/index and note about the move. [1][2]
Sources:
[1] https://www.elastic.co/guide/en/apm/guide/index.html
[2] https://www.elastic.co/guide/en/apm/guide/8.18/index.html
🌐 Web query:
OpenTelemetry Collector Configuration https://opentelemetry.io/docs/collector/configuration/
💡 Result:
The OpenTelemetry Collector configuration defines components (receivers, processors, exporters, connectors) plus optional extensions and a service section that ties them into pipelines (traces/metrics/logs). Config files are YAML (default /etc//config.yaml), can be merged from multiple files or URIs, and validated with otelcol validate. Receivers collect telemetry, processors transform/filter it, exporters send it onward, and extensions add non‑data capabilities; each component is enabled by listing it in a pipeline under service. Example configs and usage notes (endpoints, multiple component instances, file includes, env/URI config sources) are on the docs page. (opentelemetry.io)
Citations:
🌐 Web query:
Traceloop SDK Configuration https://www.traceloop.com/docs/openllmetry/configuration
💡 Result:
Summary of Traceloop SDK configuration options (from Traceloop docs): [1]
- Application name: set via SDK init (e.g., Traceloop.init(app_name="my app")).
- Resource attributes: add custom OpenTelemetry resource attrs (e.g., resource_attributes={"env":"prod"}).
- Base URL: defaults to https://api.traceloop.com (SDK appends /v1/traces); http/https → OTLP/HTTP, otherwise OTLP/gRPC.
- API key: sent as Bearer token; if not set and base URL is traceloop, SDK can auto-generate a key.
- Headers: custom HTTP headers (W3C correlation-context format); overrides API key if set.
- Custom exporter: option to provide your own traces exporter (e.g., Zipkin, Jaeger); overrides base URL/API key/headers.
- Disable batch: option to disable OpenTelemetry batch span processor.
- Disable tracing of prompt content: opt out of recording prompts/completions/embeddings.
- Control logging: set SDK log level (debug/info/warn/error).
- Control telemetry: disable anonymous SDK telemetry (TRACELOOP_TELEMETRY).
- Enrich metrics/traces: toggle enrichment (may add latency on first request).
- Traceloop Sync: opt-in sync for prompts/registry and related settings (enabled via TRACELOOP_SYNC_* env vars).
- Instrumentations: auto-detects instrumentations; can explicitly enable or block specific instruments.
See full docs for examples and environment variable names. [1]
Source: Traceloop SDK Initialization Options — Configuration. [1]
Update Elastic APM documentation link — current URL is outdated.
The Elastic APM link (https://www.elastic.co/guide/en/apm/guide/current/index.html) is legacy. The APM guide now lives under https://www.elastic.co/guide/en/apm/guide/index.html (and content has moved to the Observability guide since v8.12). Update the reference to prevent users from accessing outdated pages.
The OpenTelemetry Collector Configuration and Traceloop SDK Configuration links are current and valid.
🤖 Prompt for AI Agents
In openllmetry/integrations/elasticsearch-apm.mdx around lines 300 to 302, the
Elastic APM link is outdated; replace the legacy URL
https://www.elastic.co/guide/en/apm/guide/current/index.html with the updated
canonical URL https://www.elastic.co/guide/en/apm/guide/index.html so the
documentation points to the current APM/Observability guide; leave the other two
links unchanged.
![ellipsis-dev[bot]](https://avatars.githubusercontent.com/in/64358?s=60&v=4){kind=small}
There was a problem hiding this comment.
Important
Looks good to me! 👍
Reviewed everything up to a39f6ec in 2 minutes and 15 seconds. Click for details.
- Reviewed
308lines of code in1files - Skipped
2files when reviewing. - Skipped posting
3draft comments. View those below. - Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.
1. openllmetry/integrations/elasticsearch-apm.mdx:6
- Draft comment:
Naming inconsistency: both 'OpenLLMetry' and 'Traceloop' are used. Consider unifying the terminology throughout the guide for clarity. - Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 50% Looking at the actual usage, it seems like "OpenLLMetry" and "Traceloop" are not interchangeable terms being used inconsistently, but rather refer to different things: OpenLLMetry is the product/solution name, while Traceloop SDK is the implementation package. The comment suggests changing "Traceloop OpenLLMetry client" to "the Traceloop SDK", but this might actually reduce clarity since the current phrasing connects the SDK to the OpenLLMetry product. This appears to be a stylistic preference rather than a genuine error. The document is consistent in using "Traceloop SDK" when referring to the package and "OpenLLMetry" when referring to the observability solution. I might be missing that there's an official branding guideline that says only one term should be used. The comment could be correct if the product has been rebranded or if there's confusion in the marketplace about the naming. Even if there are branding guidelines, this comment is making a stylistic suggestion about terminology without clear evidence that the current usage is wrong. The dual terminology appears intentional and serves to distinguish the product (OpenLLMetry) from the implementation (Traceloop SDK). Without strong evidence that this is incorrect, this falls into the category of subjective style preferences. This comment should be deleted. It's a stylistic suggestion about terminology that appears to be intentionally used to distinguish between the product name (OpenLLMetry) and the SDK package name (Traceloop SDK). There's no strong evidence this is incorrect or confusing.
2. openllmetry/integrations/elasticsearch-apm.mdx:8
- Draft comment:
Ensure that custom MDX components (, , , , , , ) are properly registered in your documentation framework so they render as expected. - Reason this comment was not posted:
Comment did not seem useful. Confidence is useful =0%<= threshold50%This comment is asking the PR author to ensure that custom MDX components are properly registered. It doesn't provide a specific suggestion or point out a specific issue with the code. It falls under the rule of not asking the author to ensure something is done without being specific.
3. openllmetry/integrations/elasticsearch-apm.mdx:93
- Draft comment:
Consider quoting endpoint values in the YAML configuration (e.g., 'localhost:4318' and 'http://localhost:8200') to avoid potential parsing issues in stricter YAML parsers. - Reason this comment was not posted:
Confidence changes required:50%<= threshold50%None
Workflow ID: wflow_Novg4SxkH2pH1SVb
You can customize 
2 participants
Summary
Adds comprehensive documentation for integrating OpenLLMetry with Elasticsearch APM, enabling users to visualize LLM traces in Kibana's native APM interface using OpenTelemetry Protocol (OTLP).
What's Changed
openllmetry/integrations/elasticsearch-apm.mdx(302 lines)Supporting screenshots:
img/integrations/elasticsearch-apm.png- Trace timeline view in Kibana APMimg/integrations/elasticsearch-apm-trace-details.png- Detailed span metadata viewKey Features Documented
@workflowand@taskdecorators for complex multi-step applicationsDocumentation Structure
Testing
Important
Adds a comprehensive guide for integrating OpenLLMetry with Elasticsearch APM, including setup instructions, configuration examples, and production considerations.
elasticsearch-apm.mdxwith 302 lines detailing integration of OpenLLMetry with Elasticsearch APM.elasticsearch-apm.pngandelasticsearch-apm-trace-details.pngfor trace visualization in Kibana.This description was created by
for a39f6ec. You can customize this summary. It will automatically update as commits are pushed.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.