fix(docs): remove stale jaeger-collector/ingester references from v2 …#1114
Open
Abhay-sonkar wants to merge 7 commits into
Open
fix(docs): remove stale jaeger-collector/ingester references from v2 …#1114Abhay-sonkar wants to merge 7 commits into
Abhay-sonkar wants to merge 7 commits into
Conversation
…docs Jaeger v2 replaced the standalone jaeger-collector/jaeger-ingester binaries with a single unified jaeger binary built on the OpenTelemetry Collector framework. These two files still described scaling/deployment advice as if jaeger-collector and jaeger-ingester were separate deployable binaries. Signed-off-by: Abhay Kumar Sonkar <kumar.abhay44444@gmail.com>
…19 docs Signed-off-by: Abhay Kumar Sonkar <kumar.abhay44444@gmail.com>
There was a problem hiding this comment.
Pull request overview
This PR updates Jaeger v2 documentation to remove stale references to Jaeger v1 standalone binaries (collector/query/ingester/agent) and to describe scaling/deployment guidance in terms of the unified jaeger binary and its internal pipelines.
Changes:
- Updates performance tuning guidance to discuss scaling multiple
jaegerinstances (instead ofjaeger-collector) and Kafka buffering/consumption in v2 terms. - Updates FAQ guidance to refer to “multiple instances” (instead of “multiple collectors”) and removes v1-component wording in v2.19.
- Aligns wording with the Jaeger v2 unified-binary architecture described elsewhere in the v2 docs.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 8 comments.
| File | Description |
|---|---|
| content/docs/v2/2.19/operations/performance-tuning.md | Rewords scaling/storage/Kafka sections to avoid v1 jaeger-collector/jaeger-ingester references. |
| content/docs/v2/2.19/faq.md | Renames/rewrites “multiple collectors” guidance to “multiple instances” and updates the “UI-only” Q&A wording. |
| content/docs/v2/_dev/operations/performance-tuning.md | Updates scaling/Kafka guidance to describe collector/ingester pipelines inside the unified binary. |
| content/docs/v2/_dev/faq.md | Updates the “multiple collectors” question to “multiple instances” and adjusts wording around the collector pipeline. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| Each span is written to the storage by **jaeger-collector** using one worker, blocking it until the span has been stored. When the storage is too slow, the number of workers blocked by the storage might be too high, causing spans to be dropped. To help diagnose this situation, the histogram `jaeger_collector_save_latency_bucket` can be analyzed. Ideally, the latency should remain the same over time. When the histogram shows that most spans are taking longer and longer over time, it’s a good indication that your storage might need some attention. | ||
|
|
||
| Each span is written to the storage by the **jaeger** binary using one worker, blocking it until the span has been stored. When the storage is too slow, the number of workers blocked by the storage might be too high, causing spans to be dropped. To help diagnose this situation, the histogram `jaeger_collector_save_latency_bucket` can be analyzed. Ideally, the latency should remain the same over time. When the histogram shows that most spans are taking longer and longer over time, it's a good indication that your storage might need some attention. |
|
|
||
| Jaeger [can use Apache Kafka](../../architecture/) as a buffer between **jaeger-collector** and the actual backing storage (Elasticsearch, Apache Cassandra). This is ideal for cases where the traffic spikes are relatively frequent (prime time traffic) but the storage can eventually catch up once the traffic normalizes. Please refer to the [Kafka page](../../storage/kafka/) for details on configuring this deployment. | ||
|
|
||
| Jaeger [can use Apache Kafka](../../architecture/) as a buffer between the **jaeger** binary and the actual backing storage (Elasticsearch, Apache Cassandra). This is ideal for cases where the traffic spikes are relatively frequent (prime time traffic) but the storage can eventually catch up once the traffic normalizes. Please refer to the [Kafka page](../../storage/kafka/) for details on configuring this deployment. |
| **jaeger-collector**s can still be scaled in the same way as when writing to storage directly. The trace IDs are used as sharding keys for Kafka partitions, such that all spans for a given trace end up in the same partition of the Kafka topic. Each **jaeger-collector** can write to any partition. | ||
|
|
||
| **jaeger-ingester**s can also be scaled as needed to sustain the throughput. They will automatically negotiate and rebalance Kafka partitions among them. However, it does not make sense to run more **jaeger-ingester**s than there are partitions in the Kafka topic, as in this case some of **jaeger-ingester**s will be idle. | ||
| **jaeger** instances can still be scaled in the same way as when writing to storage directly. The trace IDs are used as sharding keys for Kafka partitions, such that all spans for a given trace end up in the same partition of the Kafka topic. Each **jaeger** instance can write to any partition, and instances configured to consume from Kafka will automatically negotiate and rebalance Kafka partitions among them. However, it does not make sense to run more instances than there are partitions in the Kafka topic, as in this case some instances will be idle. No newline at end of file |
| ## Do I need to run multiple instances? | ||
|
|
||
| > Does having high availability of **jaeger-collector** improve the overall system performance like decreasing the dropped span count and having the less outage for trace collection? Is it recommended? If yes, why? | ||
| > Does having high availability of the **jaeger** binary improve the overall system performance like decreasing the dropped span count and having less outage for trace collection? Is it recommended? If yes, why? |
| ## Can I run only Jaeger UI if I am already storing data in Elasticsearch/ClickHouse? | ||
|
|
||
| Q: I am already sending traces and metrics to my Elasticsearch cloud setup using sidecar containers and OpenTelemetry Collector (with index pattern: `traces-${date}`). I want to visualize them via the Jaeger UI. Can I run only the query service and the UI, without running Jaeger collector? | ||
| Q: I am already sending traces and metrics to my Elasticsearch cloud setup using sidecar containers and OpenTelemetry Collector (with index pattern: `traces-${date}`). I want to visualize them via the Jaeger UI. Can I run only the query service and the UI, without running the rest of the **jaeger** binary's pipeline? |
| ## Do I need to run multiple instances? | ||
|
|
||
| > Does having high availability of **jaeger-collector** improve the overall system performance like decreasing the dropped span count and having the less outage for trace collection? Is it recommended? If yes, why? | ||
| > Does having high availability of the collector pipeline improve the overall system performance like decreasing the dropped span count and having less outage for trace collection? Is it recommended? If yes, why? |
Comment on lines
+45
to
+47
| ## Do I need to run multiple instances? | ||
|
|
||
| > Does having high availability of **jaeger-collector** improve the overall system performance like decreasing the dropped span count and having the less outage for trace collection? Is it recommended? If yes, why? | ||
| > Does having high availability of the collector pipeline improve the overall system performance like decreasing the dropped span count and having less outage for trace collection? Is it recommended? If yes, why? |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Abhay Kumar Sonkar <Kumar.abhay44444@gmail.com>
|
|
||
| Jaeger [can use Apache Kafka](../../architecture/) as a buffer between **jaeger-collector** and the actual backing storage (Elasticsearch, Apache Cassandra). This is ideal for cases where the traffic spikes are relatively frequent (prime time traffic) but the storage can eventually catch up once the traffic normalizes. Please refer to the [Kafka page](../../storage/kafka/) for details on configuring this deployment. | ||
|
|
||
| Jaeger [can use Apache Kafka](../../architecture/) as a buffer between the **jaeger** binary and the actual backing storage (Elasticsearch, Apache Cassandra). This is ideal for cases where the traffic spikes are relatively frequent (prime time traffic) but the storage can eventually catch up once the traffic normalizes. Please refer to the [Kafka page](../../storage/kafka/) for details on configuring this deployment. |
| ## Do I need to run multiple instances? | ||
|
|
||
| > Does having high availability of **jaeger-collector** improve the overall system performance like decreasing the dropped span count and having the less outage for trace collection? Is it recommended? If yes, why? | ||
| > Does having high availability of the **jaeger** binary improve the overall system performance like decreasing the dropped span count and having less outage for trace collection? Is it recommended? If yes, why? |
| ## Do I need to run multiple instances? | ||
|
|
||
| > Does having high availability of **jaeger-collector** improve the overall system performance like decreasing the dropped span count and having the less outage for trace collection? Is it recommended? If yes, why? | ||
| > Does having high availability of the collector pipeline improve the overall system performance like decreasing the dropped span count and having less outage for trace collection? Is it recommended? If yes, why? |
Comment on lines
+45
to
+47
| ## Do I need to run multiple instances? | ||
|
|
||
| > Does having high availability of **jaeger-collector** improve the overall system performance like decreasing the dropped span count and having the less outage for trace collection? Is it recommended? If yes, why? | ||
| > Does having high availability of the collector pipeline improve the overall system performance like decreasing the dropped span count and having less outage for trace collection? Is it recommended? If yes, why? |
…Copilot review Signed-off-by: Abhay Kumar Sonkar <kumar.abhay44444@gmail.com>
| ## Can I run only Jaeger UI if I am already storing data in Elasticsearch/ClickHouse? | ||
|
|
||
| Q: I am already sending traces and metrics to my Elasticsearch cloud setup using sidecar containers and OpenTelemetry Collector (with index pattern: `traces-${date}`). I want to visualize them via the Jaeger UI. Can I run only the query service and the UI, without running Jaeger collector? | ||
| Q: I am already sending traces and metrics to my Elasticsearch cloud setup using sidecar containers and OpenTelemetry Collector (with index pattern: `traces-${date}`). I want to visualize them via the Jaeger UI. Can I run only the query service and the UI, without running the rest of the **jaeger** binary's pipeline? |
|
|
||
| Each span is written to the storage by **jaeger-collector** using one worker, blocking it until the span has been stored. When the storage is too slow, the number of workers blocked by the storage might be too high, causing spans to be dropped. To help diagnose this situation, the histogram `jaeger_collector_save_latency_bucket` can be analyzed. Ideally, the latency should remain the same over time. When the histogram shows that most spans are taking longer and longer over time, it’s a good indication that your storage might need some attention. | ||
|
|
||
| Each span is written to storage by the collector pipeline using one worker, blocking it until the span has been stored. When the storage is too slow, the number of workers blocked by the storage might be too high, causing spans to be dropped. To help diagnose this situation, the histogram `jaeger_collector_save_latency_bucket` can be analyzed. Ideally, the latency should remain the same over time. When the histogram shows that most spans are taking longer and longer over time, it's a good indication that your storage might need some attention. |
| {{< /danger >}} | ||
|
|
||
| Each span is written to the storage by **jaeger-collector** using one worker, blocking it until the span has been stored. When the storage is too slow, the number of workers blocked by the storage might be too high, causing spans to be dropped. To help diagnose this situation, the histogram `jaeger_collector_save_latency_bucket` can be analyzed. Ideally, the latency should remain the same over time. When the histogram shows that most spans are taking longer and longer over time, it’s a good indication that your storage might need some attention. | ||
| Each span is written to storage by the collector pipeline using one worker, blocking it until the span has been stored. When the storage is too slow, the number of workers blocked by the storage might be too high, causing spans to be dropped. To help diagnose this situation, the histogram `jaeger_collector_save_latency_bucket` can be analyzed. Ideally, the latency should remain the same over time. When the histogram shows that most spans are taking longer and longer over time, it's a good indication that your storage might need some attention. |
Comment on lines
+50
to
+51
| * Your clients send so much data that a single instance is not able to accept it fast enough. | ||
| * You want higher availability, e.g., when you do rolling restarts for upgrade, to have some instances still running and able to process inbound data. |
| Jaeger v2 is distributed as a single `jaeger` binary. The collector functionality is one of the pipelines configured within it. Use the auto-scaling capabilities of your platform to run multiple instances of the binary horizontally. | ||
|
|
||
| Adding **jaeger-collector** instances is recommended when your platform provides auto-scaling capabilities, or when it's easier to start/stop **jaeger-collector** instances than changing existing, running instances. Scaling horizontally is also indicated when the CPU usage should be spread across nodes. | ||
| Running additional instances is recommended when your platform provides auto-scaling capabilities, or when it's easier to start/stop instances than changing existing, running ones. Scaling horizontally is also indicated when the CPU usage should be spread across nodes. |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Abhay Kumar Sonkar <Kumar.abhay44444@gmail.com>
Author
|
Applied all remaining Copilot suggestions across all four files (_dev/faq.md, 2.19/faq.md, _dev/operations/performance-tuning.md, and 2.19/operations/performance-tuning.md). Verified using findstr that no stale jaeger-collector references, "less outage" grammar issues, or "without running Jaeger collector" wording remain in any of the modified files, excluding the intentionally preserved jaeger_collector_save_latency_bucket metric identifier. |
Comment on lines
+47
to
+51
| > Does having high availability of the collector pipeline improve the overall system performance like decreasing the dropped span count and having fewer outages for trace collection? Is it recommended? If yes, why? | ||
|
|
||
| These are the reasons to run multiple instances: | ||
| * Your clients send so much data that a single **jaeger-collector** is not able to accept it fast enough. | ||
| * You want higher availability, e.g., when you do rolling restarts of **jaeger-collector**s for upgrade, to have some instances still running and able to process inbound data. | ||
| * Your clients send so much data that a single instance is not able to accept it fast enough. | ||
| * You want higher availability, e.g., when you do rolling restarts for upgrade, to have some instances still running and able to process inbound data. |
Comment on lines
+47
to
+51
| > Does having high availability of the **jaeger** binary improve the overall system performance like decreasing the dropped span count and having fewer outages for trace collection? Is it recommended? If yes, why? | ||
|
|
||
| These are the reasons to run multiple instances: | ||
| * Your clients send so much data that a single **jaeger-collector** is not able to accept it fast enough. | ||
| * You want higher availability, e.g., when you do rolling restarts of **jaeger-collector**s for upgrade, to have some instances still running and able to process inbound data. | ||
| * Your clients send so much data that a single **jaeger** instance is not able to accept it fast enough. | ||
| * You want higher availability, e.g., when you do rolling restarts of **jaeger** instances for upgrade, to have some instances still running and able to process inbound data. |
Comment on lines
62
to
+66
| ## Can I run only Jaeger UI if I am already storing data in Elasticsearch/ClickHouse? | ||
|
|
||
| Q: I am already sending traces and metrics to my Elasticsearch cloud setup using sidecar containers and OpenTelemetry Collector (with index pattern: `traces-${date}`). I want to visualize them via the Jaeger UI. Can I run only the query service and the UI, without running Jaeger collector? | ||
| Q: I am already sending traces and metrics to my Elasticsearch cloud setup using sidecar containers and OpenTelemetry Collector (with index pattern: `traces-${date}`). I want to visualize them via the Jaeger UI. Can I run only the query service and the UI, without running the rest of the **jaeger** binary's pipeline? | ||
|
|
||
| A: No, we do not support that setup. Every exporter can choose a different way of storing traces in the database like Elasticsearch or ClickHouse. Jaeger has its own storage implementation used by both collector and query service which uses a database schema that is specific to Jaeger and may not be compatible with the schema used by other exporters. | ||
| A: No, we do not support that setup. Every exporter can choose a different way of storing traces in the database like Elasticsearch or ClickHouse. Jaeger has its own storage implementation used by both the ingestion pipeline and query service, which uses a database schema that is specific to Jaeger and may not be compatible with the schema used by other exporters. No newline at end of file |
Comment on lines
+8
to
+12
| Jaeger was built to be able to ingest huge amounts of data in a resilient way. To better utilize resources that might cause delays, such as storage or network communications, Jaeger buffers and batches data. When more spans are generated than Jaeger is able to safely process, spans might get dropped. However, the defaults might not fit all scenarios. | ||
|
|
||
| Since Jaeger v2 is based on the OpenTelemetry Collector, most of the advice in the [Scaling the Collector documentation](https://opentelemetry.io/docs/collector/scaling/) applies to Jaeger as well. | ||
|
|
||
| Although performance tuning the individual components is important, the way Jaeger is deployed can be decisive in obtaining optimal performance. | ||
|
|
||
| ## Scale the Collector up and down | ||
|
|
||
| Use the auto-scaling capabilities of your platform: **jaeger-collector** is nearly horizontally scalable so that more instances can be added and removed on-demand. | ||
|
|
||
| Adding **jaeger-collector** instances is recommended when your platform provides auto-scaling capabilities, or when it's easier to start/stop **jaeger-collector** instances than changing existing, running instances. Scaling horizontally is also indicated when the CPU usage should be spread across nodes. | ||
|
|
||
| ## Scale up and down | ||
| Use the auto-scaling capabilities of your platform: the unified **jaeger** binary is nearly horizontally scalable so that more instances can be added and removed on-demand. |
Signed-off-by: Abhay Kumar Sonkar <kumar.abhay44444@gmail.com>
…ub.com/Abhay-sonkar/documentation into fix/v2-docs-stale-collector-references
| {{< /danger >}} | ||
|
|
||
| Each span is written to the storage by **jaeger-collector** using one worker, blocking it until the span has been stored. When the storage is too slow, the number of workers blocked by the storage might be too high, causing spans to be dropped. To help diagnose this situation, the histogram `jaeger_collector_save_latency_bucket` can be analyzed. Ideally, the latency should remain the same over time. When the histogram shows that most spans are taking longer and longer over time, it’s a good indication that your storage might need some attention. | ||
| Each span is written to storage by the collector pipeline using one worker, blocking it until the span has been stored. When the storage is too slow, the number of workers blocked by the storage might be too high, causing spans to be dropped. To help diagnose this situation, the histogram `jaeger_collector_save_latency_bucket` can be analyzed. Ideally, the latency should remain the same over time. When the histogram shows that most spans are taking longer and longer over time, it's a good indication that your storage might need some attention. |
| {{< /danger >}} | ||
|
|
||
| Each span is written to the storage by **jaeger-collector** using one worker, blocking it until the span has been stored. When the storage is too slow, the number of workers blocked by the storage might be too high, causing spans to be dropped. To help diagnose this situation, the histogram `jaeger_collector_save_latency_bucket` can be analyzed. Ideally, the latency should remain the same over time. When the histogram shows that most spans are taking longer and longer over time, it’s a good indication that your storage might need some attention. | ||
| Each span is written to storage by the collector pipeline using one worker, blocking it until the span has been stored. When the storage is too slow, the number of workers blocked by the storage might be too high, causing spans to be dropped. To help diagnose this situation, the histogram `jaeger_collector_save_latency_bucket` can be analyzed. Ideally, the latency should remain the same over time. When the histogram shows that most spans are taking longer and longer over time, it's a good indication that your storage might need some attention. |
| Jaeger [can use Apache Kafka](../../architecture/) as a buffer between **jaeger-collector** and the actual backing storage (Elasticsearch, Apache Cassandra). This is ideal for cases where the traffic spikes are relatively frequent (prime time traffic) but the storage can eventually catch up once the traffic normalizes. Please refer to the [Kafka page](../../storage/kafka/) for details on configuring this deployment. | ||
| Jaeger [can use Apache Kafka](../../architecture/) as a buffer between the collector pipeline and the actual backing storage (Elasticsearch, Apache Cassandra). This is ideal for cases where the traffic spikes are relatively frequent (prime time traffic) but the storage can eventually catch up once the traffic normalizes. Please refer to the [Kafka page](../../storage/kafka/) for details on configuring this deployment. | ||
|
|
||
| In addition to the performance aspects, having spans written to Kafka is useful for building real time data pipeline for aggregations and feature extraction from traces. |
| Jaeger [can use Apache Kafka](../../architecture/) as a buffer between **jaeger-collector** and the actual backing storage (Elasticsearch, Apache Cassandra). This is ideal for cases where the traffic spikes are relatively frequent (prime time traffic) but the storage can eventually catch up once the traffic normalizes. Please refer to the [Kafka page](../../storage/kafka/) for details on configuring this deployment. | ||
| Jaeger [can use Apache Kafka](../../architecture/) as a buffer between the collector pipeline and the actual backing storage (Elasticsearch, Apache Cassandra). This is ideal for cases where the traffic spikes are relatively frequent (prime time traffic) but the storage can eventually catch up once the traffic normalizes. Please refer to the [Kafka page](../../storage/kafka/) for details on configuring this deployment. | ||
|
|
||
| In addition to the performance aspects, having spans written to Kafka is useful for building real time data pipeline for aggregations and feature extraction from traces. |
Comment on lines
+47
to
+51
| > Does having high availability of the collector pipeline improve the overall system performance like decreasing the dropped span count and having fewer outages for trace collection? Is it recommended? If yes, why? | ||
|
|
||
| These are the reasons to run multiple instances: | ||
| * Your clients send so much data that a single **jaeger-collector** is not able to accept it fast enough. | ||
| * You want higher availability, e.g., when you do rolling restarts of **jaeger-collector**s for upgrade, to have some instances still running and able to process inbound data. | ||
| * Your clients send so much data that a single instance is not able to accept it fast enough. | ||
| * You want higher availability, e.g., when you do rolling restarts for upgrade, to have some instances still running and able to process inbound data. |
Author
|
@yurishkuro — this PR cleans up outdated v1 architecture references in the v2 documentation, specifically mentions of the standalone jaeger-collector and jaeger-ingester binaries as if they were still separate deployable components. I've gone through several rounds of Copilot review and addressed the substantive findings — a contradictory metric callout (docs said jaeger_collector_save_latency_bucket isn't available in v2 yet, then told readers to analyze it) and a terminology inconsistency between the _dev and 2.19 FAQ pages. The remaining open threads are wording/style preferences rather than factual errors, so I held off on further changes to avoid scope creep beyond the original fix. Would appreciate a human review when you have a chance — happy to address anything I've missed. |
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
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.
Which problem is this PR solving?
Fixes #1113
Jaeger v2 replaced the standalone
jaeger-collector,jaeger-query,jaeger-ingester, andjaeger-agentbinaries with a single unifiedjaegerbinary built on the OpenTelemetry Collector framework (as described inv2/_dev/_index.md). These documentation pages still referenced the old v1 architecture and its scaling/deployment model without being updated for Jaeger v2. This can mislead users deploying or scaling Jaeger v2.Description of the changes
content/docs/v2/_dev/operations/performance-tuning.mdandcontent/docs/v2/2.19/operations/performance-tuning.md— updated the "Scale the Collector up and down", "Make sure the storage can keep up", and "Consider using Kafka as intermediate buffer" sections to reflect the Jaeger v2 architecture by describing scaling and operation through multiple instances of the unifiedjaegerbinary instead of the standalonejaeger-collectorbinary, which no longer exists in v2. The metric namejaeger_collector_save_latency_bucketwas intentionally left unchanged since it is an actual metric identifier, not documentation prose.content/docs/v2/_dev/faq.mdandcontent/docs/v2/2.19/faq.md— updated the "Do I need to run multiple instances?" section (previously "Do I need to run multiple collectors?") and the "Can I run only Jaeger UI if I am already storing data in Elasticsearch/ClickHouse?" section to reflect the same unified-binary architecture, removing references tojaeger-ingesteras a separate deployable binary.No content was removed beyond references to the old architecture. The underlying scaling and buffering recommendations (running multiple instances and using Kafka as an intermediate buffer) are still valid and have been preserved, but are now described correctly for Jaeger v2.
How was this change tested?
Manually reviewed all four updated pages against the current
cmd/directory on themainbranch, which contains only the unifiedjaegerbinary. Confirmed thatjaeger-collector,jaeger-query, andjaeger-ingesterno longer exist as standalone binaries. This is a documentation-only change with no code or build impact.Checklist