docs: Add Set Custom Attributes doc #2184
Conversation
Signed-off-by: Jugal Kishore <[email protected]>
crazyuploader
requested review from
makeavish,
pranay01 and
therealpandey
as code owners
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Claude finished @crazyuploader's task —— View job Documentation Review CompleteI've reviewed this PR against the repository's CONTRIBUTING.md guidelines. The document provides solid technical content about setting custom attributes in OpenTelemetry, but needs some structural improvements to meet the documentation standards. Summary of FindingsCritical Issues (Must Fix)
Important Improvements (Should Fix)
Technical Accuracy✅ All processor configurations verified against official OpenTelemetry sources:
PR Checklist ComplianceComparing against the PR Checklist:
Recommendations
The content is technically accurate and comprehensive - these changes will align it with the repository's documentation standards and improve usability. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
|
|
||
| ## Overview | ||
|
|
||
| Attributes/Resource attributes provide additional contextual information about the source and type of telemetry data, such as service name, environment, hostname, etc. Attributes help in better filtering, grouping, correlation of telemetry data in SigNoz. |
There was a problem hiding this comment.
Missing Prerequisites section. According to CONTRIBUTING.md, documentation should include a Prerequisites section listing versions, accounts, keys, cluster access, etc., with links.
For this guide, consider adding prerequisites such as:
- OpenTelemetry Collector version requirements
- SDK versions for each language
- SigNoz deployment (Cloud or Self-Hosted)
Source: CONTRIBUTING.md lines 109-110
There was a problem hiding this comment.
@crazyuploader Add prerequisites section here mentioning OTel setup. Understanding otel config (link our config explanation doc) - Only relevant when you are using otel collector
|
|
||
| ## Overview | ||
|
|
||
| Attributes/Resource attributes provide additional contextual information about the source and type of telemetry data, such as service name, environment, hostname, etc. Attributes help in better filtering, grouping, correlation of telemetry data in SigNoz. |
There was a problem hiding this comment.
Missing Validate section. According to CONTRIBUTING.md, docs should include a "Validate" section showing how to confirm success (UI path, endpoint, example output).
Consider adding a section showing:
- How to view the custom attributes in SigNoz UI
- Where to find them in Traces/Logs/Metrics explorers
- Screenshots of the UI showing the custom attributes
Source: CONTRIBUTING.md lines 111-112
|
|
||
| ## Overview | ||
|
|
||
| Attributes/Resource attributes provide additional contextual information about the source and type of telemetry data, such as service name, environment, hostname, etc. Attributes help in better filtering, grouping, correlation of telemetry data in SigNoz. |
There was a problem hiding this comment.
Missing Next Steps section. According to CONTRIBUTING.md, docs should include a short "Next steps" section linking to adjacent features or deeper guides.
Consider adding links to:
- Query Builder documentation for filtering by custom attributes
- Alert Management for creating alerts based on attributes
- Dashboard creation guides
Source: CONTRIBUTING.md lines 324-325
| exporters: [otlp] | ||
| ``` | ||
|
|
||
| This example includes resource detection processor setup to automatically include resource attributes from the environment, host system, Docker containers, Kubernetes nodes. The complete list of supported detectors can be found [here](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/resourcedetectionprocessor/README.md#supported-detectors). |
There was a problem hiding this comment.
Link to official documentation is good, but consider cross-linking to SigNoz's OTel Collector configuration guide as recommended in CONTRIBUTING.md.
Add: "For more details on collector configuration, see the OpenTelemetry Collector configuration guide."
Source: CONTRIBUTING.md lines 73, 228
| } | ||
| ``` | ||
|
|
||
| For more information on how to Instrument a .NET app, check this [guide](https://signoz.io/docs/instrumentation/opentelemetry-dotnet/). |
There was a problem hiding this comment.
Good cross-reference to related documentation. Consider using the full absolute URL format as recommended in CONTRIBUTING.md:
https://signoz.io/docs/instrumentation/opentelemetry-dotnet/
Source: CONTRIBUTING.md line 163
| # Set service name separately | ||
| export OTEL_SERVICE_NAME="my-log-service" | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Missing Troubleshooting section. According to CONTRIBUTING.md lines 112-113, 271-273, and 323, docs should include a Troubleshooting section covering common issues like:
- Attributes not appearing in SigNoz after configuration
- Processor configuration errors in the collector
- SDK instrumentation issues
- Common validation failures
This is especially important for Send Data / instrumentation docs.
| # Set service name separately | ||
| export OTEL_SERVICE_NAME="my-log-service" | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Missing Next Steps section. According to CONTRIBUTING.md lines 303, 324-325, docs should include a short "Next steps" section linking to adjacent features such as:
- Query Builder documentation for filtering by custom attributes
- Alert Management for creating alerts based on attributes
- Dashboard creation guides using custom attributes
This helps complete the end-to-end workflow as recommended in CONTRIBUTING.md line 274.
| export OTEL_RESOURCE_ATTRIBUTES="service.name=my-log-service,service.version=1.0.0,deployment.environment=production,custom.team=backend" | ||
| ``` | ||
|
|
||
| ### Setting Service Name Separately |
There was a problem hiding this comment.
The section title "Setting Service Name Separately" doesn't accurately reflect what OTEL_SERVICE_NAME does in the context of this document. This section is about setting resource attributes, and OTEL_SERVICE_NAME is just one specific resource attribute. Consider:
- Renaming to "Service Name" or "Setting Service Name"
- Explaining that service name is a special resource attribute that can be set separately
- Noting that this is equivalent to setting
service.nameinOTEL_RESOURCE_ATTRIBUTES
This addresses makeavish's comment about "Why name it sing attribute? It's just relevant for otel service name"
|
Claude finished @crazyuploader's task —— View job Review SummaryI've reviewed the latest version of this PR against CONTRIBUTING.md standards and verified technical accuracy against official OpenTelemetry sources. The document provides comprehensive, technically accurate content about setting custom attributes in OpenTelemetry. Good progress has been made addressing previous feedback, particularly: ✅ What's Working Well:
Issues to AddressComparing against the Docs PR Checklist: Critical Issues (Must Fix)
Missing Required SectionsPer CONTRIBUTING.md lines 107-112, these standard sections are missing:
Improvements Needed
Technical Accuracy ✅Verified against official OpenTelemetry sources: ✅ Attributes processor - ✅ Resource processor - ✅ Resource detection processor - Detectors configuration verified ✅ SDK APIs - ✅ Environment variables - All configurations and code examples are technically accurate. PR Checklist Status
SummaryThe documentation is comprehensive and technically sound. To meet repository standards, please address: Must fix (critical):
Should fix (improvements): I've provided inline comments with specific suggestions on each of these issues. The technical content is excellent—these changes will align it with documentation standards and improve usability. |
| @@ -0,0 +1,815 @@ | |||
| --- | |||
| date: 2025-11-04 | |||
| title: How to set custom Attributes in OpenTelemetry Traces, Logs and Metrics | |||
There was a problem hiding this comment.
Title improvement (per makeavish's feedback): Consider mentioning OpenTelemetry and signals explicitly in the title.
Suggested: "How to Set Custom Attributes in OpenTelemetry Traces, Logs, and Metrics"
This improves SEO and makes it clearer what the guide covers.
There was a problem hiding this comment.
@crazyuploader Take care about minor things like capitization in headings.
How to Set Custom Attributes in OpenTelemetry Traces, Logs, and Metrics
|
|
||
| Attributes/Resource attributes provide additional contextual information about the source and type of telemetry data, such as service name, environment, hostname, etc. Attributes help in better filtering, grouping, correlation of telemetry data in SigNoz. | ||
|
|
||
| ## Prerequisites |
There was a problem hiding this comment.
Prerequisites section needs expansion (per makeavish's feedback): The Prerequisites section should also mention:
- Understanding of OTel config (link to SigNoz's config explanation doc)
- Note that collector-level changes are only relevant when using OTel Collector
Source: CONTRIBUTING.md lines 109-110
| exporters: [otlp] | ||
| ``` | ||
|
|
||
| This example configuration of attributes processor deletes `http.url` attribute and hashes `db.statement` attributes from telemetry data. |
There was a problem hiding this comment.
Missing explanation of processor actions: After this code block, add a detailed explanation of what each action does:
delete: Completely removes the attribute from telemetry data (useful for sensitive data like URLs with tokens)hash: Applies SHA-256 hashing to the attribute value (for PII protection, but note that hashing is reversible if input space is small)- When to use
attributesprocessor vsresourceprocessor - Note that these actions apply to the traces, metrics, and logs pipelines
Sources:
- https://opentelemetry.io/docs/security/handling-sensitive-data/
- CONTRIBUTING.md lines 143
| exporters: [otlp] | ||
| ``` | ||
|
|
||
| This configuration does the following using resource processor: |
There was a problem hiding this comment.
Enhance processor action explanation: The current explanation is good but could be more detailed:
upsert: Sets the value regardless of whether the key exists (inserts new or updates existing)insert: Only adds the attribute if the key doesn't already exist (safe for default values)delete: Completely removes the attributehash: Applies SHA-256 hashing for PII protection (note: hashing is reversible if input space is predictable)
Also explain when to use resource processor vs attributes processor.
Sources:
- https://opentelemetry.io/docs/collector/transforming-telemetry/
- CONTRIBUTING.md line 143
|
|
||
| import GetHelp from '@/components/shared/get-help.md' | ||
|
|
||
| ## Overview |
There was a problem hiding this comment.
Missing "Validate" section (per makeavish's and previous Claude feedback): Add a ## Validate section after the SDK examples showing:
- How to view custom attributes in SigNoz UI
- Where to find them in Traces/Logs/Metrics explorers
- How to use them in the query builder
- Screenshots showing custom attributes in the UI
Source: CONTRIBUTING.md lines 111-112
|
|
||
| import GetHelp from '@/components/shared/get-help.md' | ||
|
|
||
| ## Overview |
There was a problem hiding this comment.
Missing "Troubleshooting" section (per makeavish's and previous Claude feedback): Add a ## Troubleshooting section covering:
- Attributes not appearing in SigNoz after configuration
- Collector processor configuration errors
- SDK instrumentation issues
- Pipeline misconfiguration problems
- How to verify collector is processing attributes correctly
Source: CONTRIBUTING.md lines 112-113, 271-273
| export OTEL_SERVICE_NAME="my-log-service" | ||
| ``` | ||
|
|
||
| ## Get Help |
There was a problem hiding this comment.
Missing "Next Steps" section: Add a ## Next Steps section before "Get Help" with links to:
- Query Builder documentation for filtering by custom attributes
- Alert Management for creating alerts based on attributes
- Dashboard creation guides using custom attributes
- Related instrumentation guides
Source: CONTRIBUTING.md lines 303, 324-325
|
|
||
| ## Overview | ||
|
|
||
| Attributes/Resource attributes provide additional contextual information about the source and type of telemetry data, such as service name, environment, hostname, etc. Attributes help in better filtering, grouping, correlation of telemetry data in SigNoz. |
There was a problem hiding this comment.
Missing Cloud vs Self-Host guidance: Add an Admonition noting that this guide applies to both SigNoz Cloud and Self-Hosted deployments:
<Admonition type="info">
This guide applies to both SigNoz Cloud and Self-Hosted deployments. For endpoint and authentication differences, see [Cloud vs Self-Hosted comparison](https://signoz.io/docs/ingestion/cloud-vs-self-hosted/).
</Admonition>Source: CONTRIBUTING.md lines 180-201
| exporters: [otlp] | ||
| ``` | ||
|
|
||
| This example includes resource detection processor setup to automatically include resource attributes from the environment, host system, Docker containers, Kubernetes nodes. The complete list of supported detectors can be found [here](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/resourcedetectionprocessor/README.md#supported-detectors). |
There was a problem hiding this comment.
Missing cross-link to SigNoz collector guide: Add a link to SigNoz's collector configuration guide here:
"For more details on configuring the OpenTelemetry Collector in SigNoz, see the OpenTelemetry Collector configuration guide."
Source: CONTRIBUTING.md lines 73, 228
| Before you begin, ensure you have the following prerequisites in place: | ||
|
|
||
| - **OpenTelemetry Setup**: Your application should be instrumented with OpenTelemetry. For detailed instructions, refer to our [instrumentation documentation](https://signoz.io/docs/instrumentation/). | ||
| - **OpenTelemetry Collector**: If you are using a collector, ensure it is properly configured. You can learn more about [OpenTelemetry Collector configuration here](https://signoz.io/docs/opentelemetry-collection-agents/opentelemetry-collector/configuration). |
There was a problem hiding this comment.
The link path is incorrect. The correct path based on the repository structure should be /docs/collection-agents/opentelemetry-collector/configuration/ (not /docs/opentelemetry-collection-agents/...).
| - **OpenTelemetry Collector**: If you are using a collector, ensure it is properly configured. You can learn more about [OpenTelemetry Collector configuration here](https://signoz.io/docs/opentelemetry-collection-agents/opentelemetry-collector/configuration). | |
| - **OpenTelemetry Collector**: If you are using a collector, ensure it is properly configured. You can learn more about [OpenTelemetry Collector configuration here](https://signoz.io/docs/collection-agents/opentelemetry-collector/configuration/). |
Source: CONTRIBUTING.md line 228
| - **OpenTelemetry Setup**: Your application should be instrumented with OpenTelemetry. For detailed instructions, refer to our [instrumentation documentation](https://signoz.io/docs/instrumentation/). | ||
| - **OpenTelemetry Collector**: If you are using a collector, ensure it is properly configured. You can learn more about [OpenTelemetry Collector configuration here](https://signoz.io/docs/opentelemetry-collection-agents/opentelemetry-collector/configuration). | ||
| - **A SigNoz deployment**: Either [SigNoz Cloud](https://signoz.io/teams/) or a [self-hosted](https://signoz.io/docs/install/self-host/) version. | ||
|
|
There was a problem hiding this comment.
Missing Cloud vs Self-Host guidance. According to CONTRIBUTING.md lines 180-201, when a guide applies to both environments (which this one does), include an Admonition. Consider adding after Prerequisites:
<Admonition type="info">
This guide applies to both SigNoz Cloud and Self-Hosted deployments. Configuration steps are identical for both environments.
</Admonition>
| exporters: [otlp] | ||
| ``` | ||
|
|
||
| This example configuration of attributes processor deletes `http.url` attribute and hashes `db.statement` attributes from telemetry data. |
There was a problem hiding this comment.
Good explanation! To fully address CONTRIBUTING.md lines 113-117 and 143, consider expanding this slightly to explain:
- When to use attributes processor vs resource processor (attributes processor modifies span/log/metric-level attributes, resource processor modifies service-level resource attributes)
- That the
hashaction uses SHA-256 hashing (as per OTel Collector default) - How these processors affect all three pipelines (traces, metrics, logs)
| exporters: [otlp] | ||
| ``` | ||
|
|
||
| This example includes resource detection processor setup to automatically include resource attributes from the environment, host system, Docker containers, Kubernetes nodes. The complete list of supported detectors can be found [here](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/resourcedetectionprocessor/README.md#supported-detectors). |
There was a problem hiding this comment.
Good explanation of the resource detection processor! Consider adding a brief note about when to use each detector based on deployment environment to help readers choose the right detectors for their setup:
env: Reads from OTEL_RESOURCE_ATTRIBUTES environment variablehost: Detects hostname informationsystem: Detects OS and system informationdocker: For Docker environments (requires Docker socket access)k8snode: For Kubernetes node information
| # Set service name separately | ||
| export OTEL_SERVICE_NAME="my-log-service" | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Missing Troubleshooting section. According to CONTRIBUTING.md lines 112-113, 271-273, and 323, docs should include a Troubleshooting section covering common issues like:
- Attributes not appearing in SigNoz after configuration
- Processor configuration errors in the collector
- SDK instrumentation issues
- Verification failures (e.g., attributes set but not visible)
This is especially important for Send Data / instrumentation docs.
Source: CONTRIBUTING.md lines 271-273
| # Set service name separately | ||
| export OTEL_SERVICE_NAME="my-log-service" | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Missing Next Steps section. According to CONTRIBUTING.md lines 303, 324-325, docs should include a short "Next steps" section linking to adjacent features such as:
- Query Builder documentation for filtering by custom attributes
- Alert Management for creating alerts based on attributes
- Dashboard creation guides using custom attributes
- Related feature guides (e.g., correlation, grouping)
This helps complete the end-to-end workflow as recommended in CONTRIBUTING.md line 274.
| export OTEL_RESOURCE_ATTRIBUTES="service.name=my-log-service,service.version=1.0.0,deployment.environment=production,custom.team=backend" | ||
| ``` | ||
|
|
||
| ### Setting Service Name Separately |
There was a problem hiding this comment.
The section title "Setting Service Name Separately" could be clearer. This addresses makeavish's comment: "Why name it sing attribute? It's just relevant for otel service name"
Consider renaming to just "Service Name" or "Setting Service Name" and explaining that:
OTEL_SERVICE_NAMEis a convenience environment variable specifically for theservice.nameresource attribute- It takes precedence over
service.nameinOTEL_RESOURCE_ATTRIBUTESif both are set - It's equivalent to setting
service.name=my-log-serviceinOTEL_RESOURCE_ATTRIBUTES
Source: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
makeavish
left a comment
makeavish
left a comment
There was a problem hiding this comment.
Resolve claude comments which have been addressed
2 participants
Closes: #2778
Doc: Link