Draft
Conversation
Add comprehensive documentation for Core Tracing (Trace Granularity Control) feature, enabling customers to control distributed tracing costs and volume. New documentation includes: - Introduction to Core Tracing with problem statements and use cases - Configure minimal spans tracing (MST) with per-agent instructions - Configure low-granularity tracing (LGT) with attribute details - Cost optimization strategies with service prioritization framework Updated documentation: - Added Core Tracing section to distributed tracing introduction Related JIRA: NR-497777 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Add Core Tracing section to the distributed tracing navigation menu with links to all four Core Tracing documentation pages: - Introduction to Core Tracing - Configure minimal spans tracing - Configure low-granularity tracing - Optimize distributed tracing costs Related JIRA: NR-497777 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Major corrections based on 12/5 product meeting transcript: - De-emphasize 'Core Tracing' as brand name (internal only) - Clarify these are APM agent configuration options - Specify APM agents ONLY (not OpenTelemetry) - Correct three configuration options to match product spec: * Option 1: Remove in-process spans (50-80% reduction) * Option 2: Option 1 + reduce attributes (60-75% reduction) * Option 3: Option 2 + compress duplicates (70-85% reduction) - Update span type definitions (entry, exit, in-process) - Clarify transaction trace vs distributed trace terminology Related JIRA: NR-497777 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Major terminology corrections based on product specification: - Remove "Core Tracing" branding (internal project name only) - Change from "MST"/"LGT" to "span filtering"/"attribute reduction" - Clarify Options 1-3 are sequential, not independent dials - Remove all OpenTelemetry sections (APM agents only) - Update cost optimization strategies to reflect Options 1-3 Files updated: - configure-minimal-spans-tracing.mdx: Updated to "span filtering", removed OTel - configure-low-granularity-tracing.mdx: Updated to "attribute reduction", removed OTel - cost-optimization-strategies.mdx: Reframed strategies around Options 1-3 (partial) 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
Final terminology corrections: - Updated navigation: "Core Tracing" → "Span configuration" - Updated page titles to remove "Core Tracing" branding - Updated distributed tracing intro to use Options 1-3 terminology - Completed cost optimization doc updates with Options 1-3 - Removed all "MST"/"LGT" references in favor of descriptive names All documentation now reflects accurate product specification: - APM agents only (not OpenTelemetry) - Three sequential options (not independent "dials") - No public "Core Tracing" branding 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
Major UX improvements to introduction document: - Restructured for optimal information flow (problem → value → solution) - Added concrete cost examples ($30/day → $7.50/day savings) - Removed all remaining MST/LGT terminology - Moved educational content after decision-making content - Strengthened value proposition with specific dollar amounts - Clarified sequential relationship between Options 1-3 - Updated all use case scenarios with Option 1/2/3 terminology Information architecture now follows best practices: 1. Hook with pain points (costs, gaps, limitations) 2. Value proposition with concrete examples 3. Solution overview (APM agent configuration) 4. Three options with clear trade-offs 5. When to use (scenario-based) 6. Technical details (span types, requirements) 7. Get started (next steps) 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
UX improvement to reduce cognitive load: - Converted "Challenges" section from 3 headings to 3 bullets - Converted "Span types" section from 3 headings to 3 bullets - Kept Option 1/2/3 as headings (core decision structure) Result: Reduced from 9 level-3 headings to 3 - Document feels less fragmented - Easier to scan and understand - Better visual hierarchy 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
cbehera-newrelic
added
content
|
Hi @cbehera-newrelic 👋 Thanks for your pull request! Your PR is in a queue, and a writer will take a look soon. We generally publish small edits within one business day, and larger edits within three days. Please ensure the propsed changes look good by building it first in your local environment. Refer to this contribution guide to get the site up and running in your local. If you really require a preview url, reach out to one of the writers and they will generate one for you. |
Contributor
Author
|
netlify build |
🚀 Netlify Preview Building!If the build is successful, the preview for this pull request will be available at the following URL (usually takes 10-20 minutes): https://docs-core-tracing-documentation--docs-website-netlify.netlify.app |
Major updates based on Slack thread feedback (Jan 15-26): Terminology improvements: - Replace "Options 1-3" with proper terms: reduced, essential, compact granularity - Use "partial granularity" and "full granularity" consistently - Remove obsolete "LGT" and "MST" acronyms Technical accuracy fixes: - Add note that AI spans are preserved with reduced granularity - Clarify exit span compression applies to same URLs/databases - Remove invalid NRQL query with CASE statement - Remove performance claims that vary by customer - Add bytecountestimate() limitations note Critical missing feature added: - Document hybrid sampling strategy (full + partial simultaneously) - Example: 10% full + 90% partial = 100% coverage with cost savings Cost messaging improvements: - Replace specific "typical savings" with "more cost optimization controls" - Simplify cost examples (use concrete span count example) - Avoid over-promising specific percentages Important warnings added: - Config changes require file edits + application restart - Not practical for dynamic incident response - Check dependencies on custom attributes/traced functions first Fragmentation discussion: - Expand incomplete instrumentation section to cover fragmentation - Emphasize both cost AND fragmentation as key problems solved 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Contributor
|
Netlify build |
Added Strategy 5 (Hybrid sampling) to cost-optimization-strategies.mdx to address missing feedback from Slack thread. This strategy enables both full and partial granularity tracing simultaneously on the same service for 100% trace coverage with 40-70% cost reduction. Addresses feedback from Jason Van Pelt about enabling both full and partial granularity simultaneously.
Contributor
|
Netlify build |
This commit addresses critical review feedback from Hannah and Punit: 1. Fix AI hallucination: Replace nr.lowGranularity with nr.pg - Hannah identified nr.lowGranularity as an AI hallucination - Replaced all instances with correct attribute nr.pg from CDD - Updated in NRQL queries, attribute tables, and documentation text 2. Reframe docs to emphasize fragmentation reduction (Punit's feedback) - Made fragmentation reduction the PRIMARY use case - Emphasized instrumenting non-business-critical entities - Reordered use cases to prioritize complete system visibility - De-emphasized pure cost savings as main driver 3. Add visual trace comparison examples (Punit's feedback) - Added detailed section showing waterfall views - Illustrated Full DT vs Reduced vs Essential vs Compact - Explained what changes in trace visualization for each mode - Helps users understand practical impact of configurations 4. Soften cost promise language (Andreas Can's feedback) - Updated metaDescriptions to avoid specific percentage promises - Added "Results vary by application" disclaimers - Reframed as "cost optimization controls" vs fixed savings Files modified: - introduction-core-tracing.mdx: Major reframing, added visual examples - configure-low-granularity-tracing.mdx: Fixed nr.pg attribute references - cost-optimization-strategies.mdx: Softened cost language, fixed nr.pg 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Contributor
Author
|
netlify build |
Contributor
Author
|
netlify build |
hmstepanek
suggested changes
Mar 19, 2026
Contributor
hmstepanek
left a comment
hmstepanek
left a comment
There was a problem hiding this comment.
I've run out of time for today reviewing this but I'll try to take a look at the last page tomorrow if we don't get to it in our sync. Just wanted to say thank you so much for working on this. This a huge new feature and the amount of docs we need for it is daunting so I appreciate what you have done so far on this. There's a lot of comments here-mainly related to re-organization and pulling in info from a draft PR I have.
|
|
||
| You get three configuration options for partial granularity distributed traces: | ||
|
|
||
| * **Option 1 (Span filtering):** Reduce span count by 50-80% by removing in-process spans |
Contributor
There was a problem hiding this comment.
We often reference our documentation in contractual agreements and I worry putting actual percentages in here is going to legally bind us to guarantee those percentages. We should check with leadership on whether we actually want to include percentages in here or not. It's entirely possible that using any one of these options results in a reduction of 0% depending on the service the customer is running as we found with some of our internal teams that tested this feature.
|
|
||
| * **Control ingestion** by configuring span volume and attributes | ||
| * **Fill instrumentation gaps** with lightweight traces from all services | ||
| * **Accelerate adoption** with controlled ingestion entry points for new services |
Contributor
There was a problem hiding this comment.
This item is not really part of core tracing and falls more under hybrid agent. What does fall under core tracing is configuring how many transaction to capture per minute so maybe we could change this to be:
Suggested change
| * **Accelerate adoption** with controlled ingestion entry points for new services | |
| * **Ingest control** with more options to configure how many transactions to sample per minute for a service |
| **Partial granularity metadata** | ||
| </td> | ||
| <td> | ||
| * `nr.pg` (set to `true` for identification) |
Contributor
There was a problem hiding this comment.
This is an internal hidden attribute (as indicated by the nr. prefix) and does not need to be exposed to customers.
| **Span compression metadata** (compact type only) | ||
| </td> | ||
| <td> | ||
| * `nr.durations` (sum of durations of compressed spans) |
Contributor
There was a problem hiding this comment.
Same with these-these are also internal and hidden.
|
|
||
| With attribute reduction enabled (Options 2-3), spans contain a minimal set of attributes focused on maintaining trace connectivity and service relationships: | ||
|
|
||
| ### Attributes included with attribute reduction |
Contributor
There was a problem hiding this comment.
Any attributes added in the data pipeline will still be added to the spans so it's somewhat impossible to make a complete list of attributes that a span will have. I'm not sure if we need to delve into this specific of attribute level detail here. Customers don't generally look at these attributes unless they are writing custom queries. What's more important to note that customers will certainly care about here is that custom/user attributes are dropped from spans in both essential and compact modes. Custom attributes being dropped will definitely influence their decision on which of the 3 modes they choose.
Similarly I don't think we really want to maintain a running list of all our service attributes in the docs as it will continue to grow as we support different kinds of services. This list as it is is not nearly complete but again I don't think we want or need to maintain such a list nor do our customers really care about that level of detail.
src/content/docs/distributed-tracing/core-tracing/cost-optimization-strategies.mdx
Outdated
Show resolved
Hide resolved
|
|
||
| Adaptive sampling dynamically adjusts which traces are captured based on the target you set. Lowering the adaptive sampling target reduces the number of traces sampled, which can further reduce data volume. | ||
|
|
||
| **Example scenario:** |
Contributor
There was a problem hiding this comment.
I have some example scenarios in my draft PR here that might be worth looking at/including as well. I think it's worth moving these different scenarios onto their own doc page.
| **Example scenario:** | ||
| Your checkout service is business-critical but generates 50GB/day of trace data. You need detailed traces for troubleshooting but can't afford full detail on every request. | ||
|
|
||
| * Configure 10% of traces to use full granularity (complete detail for deep analysis) |
Contributor
There was a problem hiding this comment.
Again I'm not sure about all these numbers in here but we definitely want to include a configuration example customers can copy paste for each of these. My draft PR has configuration examples included.
|
|
||
| <tr> | ||
| <td> | ||
| **Non-production** |
Contributor
There was a problem hiding this comment.
I'm not really sure about how this is broken up into production, development, etc. It's more about how quickly and how often you need detailed trace information (full granularity) for debug and deep insights vs if you are fine with capturing less detailed information. Do you have and need custom attributes? Do you have llm data (because if you do you can't use compact mode<-we need to call this out like my draft PR does)? We might need more sections here for each of the different example scenarios. I think this description under supporting service is really worded well but the others need some improvement:
Need connectivity data for complete traces, but rarely need detailed attributes. Provides cost optimization controls.
Maybe instead of the above we just need to call these different scenarios out under each of the 3 modes. Curious to get Jason's thoughts on this.
|
|
||
| ### Step 3: Calculate expected cost | ||
|
|
||
| Example calculation: |
Contributor
There was a problem hiding this comment.
I wonder if there's some way we could use our supportability metrics but have them add a drop rule to not ingest the spans and run that over a day or so to get the cost savings? cc @jvanpeltnr
hmstepanek
reviewed
Mar 19, 2026
|
|
||
| 1. **Start here**: Understand the challenges and three configuration options (reduced, essential, compact) | ||
| 2. **Learn when to use it**: Review the [six customer scenarios](#when-to-use) to see if partial granularity distributed traces fit your needs | ||
| 3. **Understand adaptive sampling**: Learn about [adaptive sampling configuration](#adaptive-sampling) for controlled ingestion |
Contributor
There was a problem hiding this comment.
Suggested change
| 3. **Understand adaptive sampling**: Learn about [adaptive sampling configuration](#adaptive-sampling) for controlled ingestion | |
| 3. **Understand how to control ingest with custom sampling configuration**: Learn about [adaptive sampling configuration](#adaptive-sampling) for controlled ingestion |
hmstepanek
reviewed
Mar 19, 2026
| Java | ||
| </td> | ||
| <td> | ||
| TBD (check with Engineering) |
Contributor
There was a problem hiding this comment.
Suggested change
| TBD (check with Engineering) | |
| 9.2.0 |
hmstepanek
reviewed
Mar 19, 2026
| Node.js | ||
| </td> | ||
| <td> | ||
| TBD (check with Engineering) |
Contributor
There was a problem hiding this comment.
Suggested change
| TBD (check with Engineering) | |
| 13.13.0 |
Implemented 8 critical fixes based on PR review feedback: 1. Remove percentage claims to avoid contractual liability - Replaced specific percentages (50-80%, 60-75%, 70-85%) with "Results vary by application" - Softened language in all cost reduction claims - Updated example scenarios to remove specific savings percentages 2. Update ingestion control messaging - Changed "Accelerate adoption" to "Ingest control with transaction sampling" - Better reflects actual feature capabilities 3. Remove internal attributes from customer docs - Removed nr.pg, nr.durations, nr.ids from attribute tables - These are internal attributes not meant for customer exposure 4. Simplify attributes section with critical custom attributes warning - Added prominent callout that custom/user attributes are DROPPED in essential/compact modes - Simplified attribute tables to focus on what matters to customers - Emphasized decision-making factors over exhaustive attribute lists 5. Update agent versions - Java: 9.2.0 - Node.js: 13.13.0 6. Add LLM data incompatibility warning - Added prominent callout that compact mode is incompatible with AI monitoring (LLM) data - Helps customers avoid configuration mistakes 7. Update adaptive sampling section heading - Changed to "Understand how to control ingest with custom sampling configuration" - More accurately describes the feature 8. Reframe service prioritization framework - Changed from production/development breakdown to use case-based framework - Focuses on: detail frequency needs, custom attribute dependencies, LLM data compatibility - Added decision checklist for customers Remaining tasks require external resources: - Adding sampler information from agent spec - Reviewing configuration examples from draft PR #22986 - Moving scenarios to dedicated page (depends on PR #22986) Files modified: - introduction-distributed-tracing.mdx - introduction-core-tracing.mdx - configure-low-granularity-tracing.mdx - cost-optimization-strategies.mdx 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Incorporated and enhanced content from hmstepanek's PR #22986, addressing remaining review feedback with copy-paste ready configuration examples. New content added: - Created sampler-configuration-examples.mdx with 5 real-world scenarios - Each example includes problem description, symptoms, and solutions - Copy-paste ready configurations for Java, Node.js, and Python - Multi-agent configuration format support Enhancements made: 1. Expanded examples with better context and symptoms 2. Added "Results" sections explaining expected outcomes 3. Included callouts for when to use each configuration 4. Added verification queries for each scenario 5. Provided configuration for multiple agent languages (Java, Node.js, Python) 6. Enhanced with decision-making guidance Examples covered: - Example 1: Fix poor endpoint distribution from upstream sampling - Solution 1: Reduce upstream sampling rate (10%) - Solution 2: Hybrid sampling (5% full + 95% partial) - Example 2: Capture rarely-called endpoints (100% partial granularity) - Example 3: Fix trace fragmentation from too many spans - Example 4: Recommended hybrid agent configuration - Example 5: Combined microservices architecture approach Integration improvements: - Added high-level sampler overview to cost-optimization-strategies.mdx - Updated navigation (distributed-tracing.yml) to include new page - Added cross-references from all related documentation pages: * introduction-core-tracing.mdx * configure-minimal-spans-tracing.mdx * configure-low-granularity-tracing.mdx * cost-optimization-strategies.mdx This addresses the remaining feedback items: - "Add high-level sampler information from agent spec" - "Review PR #22986 for configuration examples" - "Move example scenarios to dedicated page with copy-paste configs" Files modified: - src/content/docs/distributed-tracing/core-tracing/sampler-configuration-examples.mdx (NEW) - src/content/docs/distributed-tracing/core-tracing/introduction-core-tracing.mdx - src/content/docs/distributed-tracing/core-tracing/configure-minimal-spans-tracing.mdx - src/content/docs/distributed-tracing/core-tracing/configure-low-granularity-tracing.mdx - src/content/docs/distributed-tracing/core-tracing/cost-optimization-strategies.mdx - src/nav/distributed-tracing.yml 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: Hannah Stepanek <hmstepanek@gmail.com>
Addresses all critical feedback from hmstepanek's review (PR #22633). BREAKING CHANGES: 1. Removed unsupported agents (.NET, Go, Ruby, PHP) - Updated "Before you begin" to list only Java, Node.js, Python - Removed unsupported agents from requirements table - Added Python version 11.5.0 - Removed all configuration Collapser sections for unsupported agents 2. Fixed fundamental conceptual framing - Changed title: "Configure span attribute reduction" → "Configure partial granularity distributed tracing" - Reframed document to explain 3 modes (reduced, essential, compact) instead of "fine-tuning attributes" - Added "Understanding the three modes" section clarifying there's no fine-grained control - Emphasized that span filtering and attribute reduction are combined within each mode 3. Replaced incorrect configuration syntax - Removed attribute filter configurations (span_events.attributes.*) which don't work for partial granularity - Added correct sampler configuration (distributed_tracing.sampler.partial_granularity.*) - Updated configuration for all supported agents (Java, Node.js, Python) - Added environment variable examples with correct syntax 4. Fixed custom attributes documentation - Clarified custom attributes are AUTOMATICALLY dropped in essential/compact modes - Removed misleading "opt in specific custom attributes" section - Added clear guidance: use reduced granularity or full granularity if custom attributes are needed - Emphasized the 3 modes are fixed with no customization available 5. Updated verification queries - Replaced NRQL Span queries with supportability metrics - Added Metric queries using Supportability/DistributedTrace/PartialGranularity/* metrics - Provided examples for checking "Spans Kept" vs "Spans Instrumented" 6. Added hybrid sampling section - Explained full and partial granularity can be enabled simultaneously - Provided use case: 10% full + 90% partial = 100% coverage with controlled ingestion - Cross-referenced to sampler configuration examples and hybrid sampling strategy docs 7. Updated all section headings and content to use "partial granularity" terminology consistently These changes align the documentation with the actual implementation and prevent customer confusion about configuration capabilities.
…artial granularity guide Implements hmstepanek's feedback to combine configure-minimal-spans-tracing.mdx and configure-low-granularity-tracing.mdx into a single comprehensive guide. Major enhancements: 1. Added comprehensive span types explanation - Entry spans: Incoming requests to service - Exit spans: Calls to downstream services, databases, caches - In-process spans: Internal method calls - LLM/AI monitoring spans: Special handling in each mode 2. Added LLM/AI monitoring documentation - Explained LLM span handling in reduced/essential modes - Added prominent callout that compact mode is NOT compatible with AI monitoring - Clarified that LLM spans are preserved in reduced/essential but not compact 3. Added configuration precedence table - Shows which traces are captured based on enabled settings - Clarifies full vs partial granularity precedence - Covers all configuration combinations 4. Added advanced configuration examples - Basic partial granularity only configuration - Hybrid sampling with full and partial granularity - Sampling decision contexts (root, remote_parent_sampled, remote_parent_not_sampled) - Available sampler types (adaptive, always_on, always_off, trace_id_ratio_based) - Priority system explanation 5. Added special handling for ratio-based sampling - Explained the challenge when using same ratio for full and partial - Documented how agent automatically adjusts partial granularity ratio - Provided example showing ratio sum calculation 6. Enhanced "What data gets captured" section - Added configuration type for each mode (type: reduced/essential/compact) - Added reference to visual examples in introduction doc - Noted that reduced and essential look identical in DT UI 7. Updated title and metadata - Changed to "Configure partial granularity distributed tracing for APM agents" - Added "Controlled ingestion" tag - Enhanced description to mention comprehensive nature 8. Added development/staging testing tip in "Before you begin" This document now serves as the single comprehensive guide for partial granularity configuration, incorporating span filtering, attribute reduction, and advanced sampling strategies. Next steps: Update navigation to reflect this is the primary configuration guide and consider deprecating configure-minimal-spans-tracing.mdx.
Consolidates 'Configure span filtering' and 'Configure span attributes' navigation entries into a single 'Configure partial granularity' entry pointing to the comprehensive configure-low-granularity-tracing.mdx guide. Changes: - Removed 'Configure span filtering' entry (previously pointing to configure-minimal-spans-tracing) - Renamed 'Configure span attributes' to 'Configure partial granularity' - Maintained path to configure-low-granularity-tracing.mdx This reflects that these two documents have been merged into a single comprehensive guide covering all aspects of partial granularity configuration (span filtering, attribute reduction, and advanced sampling). Related to hmstepanek's feedback to combine the two configuration documents.
Replaces the old span filtering documentation with a redirect/deprecation notice that points users to the new comprehensive guide. Changes: - Replaced entire file content with redirect notice - Added prominent callout explaining the page has moved - Explained what changed (span filtering + attribute reduction now merged) - Provided clear link to new comprehensive guide - Listed related documentation for easy navigation This approach: - Prevents broken external links - Provides context for users who bookmarked the old page - Clearly explains where to find the information now - Maintains SEO continuity with redirect metadata The content from this page is now fully integrated into configure-low-granularity-tracing.mdx, which serves as the single comprehensive guide for partial granularity configuration.
…ning Implements hmstepanek's feedback to eliminate duplicate content and focus this doc on strategic planning rather than detailed mode explanations. Major changes: 1. Updated "Understand your data ingestion" section - Clarified that span count and size are controlled by the same 3 modes - Removed misleading separation of "span filtering" and "attribute reduction" - Updated to reference comprehensive configuration guide 2. Simplified Strategies 1-3 (partial granularity modes) - Removed detailed mode explanations with ASCII waterfall diagrams - Replaced with concise summaries that reference comprehensive guide - Eliminated 113 lines of duplicate content now in configure-low-granularity-tracing.mdx - Added note that visual waterfall examples are available in comprehensive guide 3. Updated Strategy 2 (formerly Strategy 4) - Adaptive sampling - Changed focus from DECREASING to INCREASING sampling target - Explained default is 10 traces/minute, max is 120 - Provided common pattern: 1 full granularity + 60 partial granularity traces/minute - Added use case: eliminating service map gaps with increased sampling + partial granularity - Aligns with actual customer needs to increase sampling, not decrease 4. Updated Strategy 3 (formerly Strategy 5) - Hybrid sampling - Added copy-paste ready configuration example showing YAML syntax - Demonstrated 10% full + 90% partial configuration - Added reference to sampler configuration examples doc 5. Updated all cross-references - Changed references from configure-minimal-spans-tracing.mdx to configure-low-granularity-tracing.mdx - Updated "What's next" section to reference merged comprehensive guide - Removed reference to separate "Configure span attributes" doc Result: This doc now focuses on its core purpose - strategic planning and rollout approach - while delegating detailed technical implementation to the comprehensive configuration guide. Eliminates confusion about span filtering and attribute reduction being "separate features" when they're actually combined in the 3 modes. Addresses feedback on lines 31, 78, 90, 193, 195, 199, 201, and 218.
…newrelic/docs-website into docs/core-tracing-documentation
Fixes reverted changes from linter/formatter and eliminates misleading parentheticals in service prioritization table. configure-low-granularity-tracing.mdx: - Fixed prerequisites section that reverted to old incorrect text about 'fine-tuning' - Restored correct prerequisites emphasizing understanding the 3 modes - Removed unsupported agents (Go, Ruby, PHP) that were re-added to requirements table - Fixed section heading from 'Configure partial granularity tracing' to 'Configure partial granularity' cost-optimization-strategies.mdx: - Removed misleading parentheticals from service prioritization table: * 'Reduced granularity (span filtering only)' → 'Reduced granularity' * 'Essential granularity (span filtering + attribute reduction)' → 'Essential granularity' * 'Compact granularity (maximum reduction)' → 'Compact granularity' - These parentheticals incorrectly implied span filtering and attribute reduction are separate features you combine, when they're actually automatically combined within each mode These changes ensure consistency with hmstepanek's feedback that the 3 modes are fixed configurations, not separate composable features.
… ingest
Implements hmstepanek's feedback (line 60) to create a dedicated page titled
"Control trace ingest with samplers" with deep technical documentation about
APM agent sampling configuration.
New document: controlling-trace-ingest.mdx
Contents:
1. How sampling works
- Sampling decision flow
- Interaction with partial granularity modes
- Trace-level vs span-level decisions
2. Sampling contexts (root, remote_parent_sampled, remote_parent_not_sampled)
- When each applies
- Use cases and common patterns
- Configuration examples
3. Sampler types
- Adaptive sampler: Dynamic adjustment to hit target traces/min
- Ratio-based sampler (trace_id_ratio_based): Consistent percentage
- Always-on sampler: 100% sampling
- Always-off sampler: 0% sampling
- When to use each type
4. Adaptive sampling targets
- Global adaptive sampling target (default 10, max 120)
- Per-context sampling targets
- Target budget and competition between contexts
- Why increase targets (fill service map gaps, improve diversity)
5. Ratio-based sampling with full and partial granularity
- The challenge: same ratios select same traces
- The solution: automatic ratio adjustment
- How agents sum ratios to ensure different traces selected
- Manual calculation examples
6. Priority and precedence
- Sampling decision precedence (full > partial, upstream > local)
- Reservoir limits and eviction rules
- Context priority order
7. Configuration precedence table
- Shows which traces captured based on enabled settings
- Clarifies full vs partial interaction
8. Common sampling patterns
- Balanced full and partial
- High-volume partial with occasional full
- Partial only for cost control
- Respect upstream decisions
9. Verification queries
- Check sampling rates
- Check sampling by context
- Verify adaptive targets are met
10. Troubleshooting
- Not enough traces
- Too many traces
- Partial granularity not appearing
This doc is distinct from sampler-configuration-examples.mdx (which shows
scenarios with copy-paste configs) - this doc provides deep technical
understanding of HOW samplers work.
Navigation: Added as second item in "Span configuration" section, after
"Control data volume" and before "Configure partial granularity".
Addresses hmstepanek's feedback about needing detailed sampler documentation
including sampler types, global vs per-section adaptive targets, and ratio
configuration details.
Adds references to the new comprehensive sampler documentation
(controlling-trace-ingest.mdx) across all partial granularity docs.
configure-low-granularity-tracing.mdx:
- Added callout in Advanced configuration examples section
- References new sampler doc for deep technical documentation
- Clarifies this section provides practical configuration examples
cost-optimization-strategies.mdx:
- Updated Understanding samplers section with quick overview
- Added callout with two distinct references:
* controlling-trace-ingest.mdx for comprehensive technical docs
* sampler-configuration-examples.mdx for real-world scenarios
- Clarified samplers determine WHICH traces, modes determine WHAT data
introduction-core-tracing.mdx:
- Added callout after adaptive sampling configuration example
- Updated Get started section to include new sampler doc
- Fixed references to point to merged comprehensive guide
- Updated terminology ('partial granularity' instead of 'span filtering')
These updates create clear navigation paths:
1. Technical deep dive → controlling-trace-ingest.mdx
2. Practical configs → configure-low-granularity-tracing.mdx
3. Real-world scenarios → sampler-configuration-examples.mdx
4. Strategic planning → cost-optimization-strategies.mdx
Contributor
Author
|
netlify build |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.