docs: document custom OTel resource attributes configuration#1910
docs: document custom OTel resource attributes configuration#1910mvanhorn wants to merge 3 commits intoopen-feature:mainfrom
Conversation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
✅ Deploy Preview for polite-licorice-3db33c ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
dosubot
bot
added
the
size:S
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request enhances the documentation for flagd's OpenTelemetry integration by providing clear guidance on how users can attach custom resource attributes to exported telemetry. This addresses a user need to enrich metrics and traces with contextual information like deployment environment or service version, improving observability and troubleshooting capabilities. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds valuable documentation for configuring custom OpenTelemetry resource attributes. The changes are clear and address the issue described. I have a couple of suggestions to improve the clarity of the examples and prevent potential user misconfiguration. Specifically, I'm suggesting a better way to present the shell command for setting environment variables and clarifying the context of the OpenTelemetry Collector configuration snippet.
docs/reference/monitoring.md
Outdated
| export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=staging,service.version=1.2.3" | ||
| flagd start --uri file:/flags.json --metrics-exporter otel --otel-collector-uri localhost:4317 |
There was a problem hiding this comment.
For better clarity and to avoid polluting the shell's environment, it's preferable to set the environment variable only for the flagd start command. This can be done in a single line. This format is also more convenient for copy-pasting and for use in container entrypoints.
| export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=staging,service.version=1.2.3" | |
| flagd start --uri file:/flags.json --metrics-exporter otel --otel-collector-uri localhost:4317 | |
| OTEL_RESOURCE_ATTRIBUTES="deployment.environment=staging,service.version=1.2.3" flagd start --uri file:/flags.json --metrics-exporter otel --otel-collector-uri localhost:4317 |
There was a problem hiding this comment.
This might also be related to #1812 and it could be like this.
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=staging,service.version=1.2.3"
export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317
flagd start --uri file:/flags.json --metrics-exporter otelIt may be better to encourage the use of OTEL environment variables in the flagd documentation, as they offer more flexible configuration options.
|
|
||
| These attributes follow the [OpenTelemetry resource semantic conventions](https://opentelemetry.io/docs/specs/semconv/resource/) and are attached to all exported metrics and traces. | ||
|
|
||
| To expose resource attributes as metric labels in Prometheus, enable `resource_to_telemetry_conversion` in your OpenTelemetry Collector exporter config: |
There was a problem hiding this comment.
To avoid potential confusion, it's better to be more explicit about where this configuration snippet fits. The current wording might lead a user to replace their entire exporters configuration, which could break other functionality like trace exporting.
| To expose resource attributes as metric labels in Prometheus, enable `resource_to_telemetry_conversion` in your OpenTelemetry Collector exporter config: | |
| To expose resource attributes as metric labels in Prometheus, update the `prometheus` exporter within the `exporters` section of your OpenTelemetry Collector configuration file as shown below: |
There was a problem hiding this comment.
Not sure about this - I don't find the original wording confusing, but up to you @mvanhorn
|
Thanks for this! Useful addition. One thought: the values here (environment, region, service version) overlap a lot with what you'd configure via static context
Otherwise LGTM, but you need to sign your commits as mentioned here as per CNCF policy. Also consider Gemini's nits. |
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adopted @erka's suggestion to use OTEL_EXPORTER_OTLP_ENDPOINT env var instead of the --otel-collector-uri flag, encouraging more flexible OTel-native configuration. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
|
Added the static context cross-reference - good call, users setting resource attributes for environment targeting will likely want the -X flags too. Also adopted @erka's suggestion to use |
3 participants
Summary
Adds documentation for defining custom OpenTelemetry resource attributes on flagd's exported telemetry using
OTEL_RESOURCE_ATTRIBUTES.Why this matters
Per #1500, users need to know how to attach custom resource attributes (deployment environment, service version, etc.) to flagd's metrics and traces. The env var works but isn't documented, and the collector-side
resource_to_telemetry_conversionsetting needed to surface them as Prometheus labels wasn't mentioned.Changes
docs/reference/monitoring.md: Added "Custom resource attributes" section between "Export to OTEL collector" and "Configure local collector setup". Documents theOTEL_RESOURCE_ATTRIBUTESenv var with example and the collector'sresource_to_telemetry_conversionconfig.Fixes #1500
This contribution was developed with AI assistance (Claude Code).