From d74900dad007389b4a98c71750ffc0cc5622a66e Mon Sep 17 00:00:00 2001 From: Abhay Kumar Sonkar Date: Wed, 8 Jul 2026 18:33:48 +0530 Subject: [PATCH 1/6] fix(docs): remove stale jaeger-collector/ingester references from v2 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 --- content/docs/v2/_dev/faq.md | 10 +++++----- .../docs/v2/_dev/operations/performance-tuning.md | 15 ++++++++------- 2 files changed, 13 insertions(+), 12 deletions(-) diff --git a/content/docs/v2/_dev/faq.md b/content/docs/v2/_dev/faq.md index 2a8a4c67..622f7ffe 100644 --- a/content/docs/v2/_dev/faq.md +++ b/content/docs/v2/_dev/faq.md @@ -42,16 +42,16 @@ Under the hood, at the data model level, the Jaeger trace IDs are a sequence of [trace-id-thrift]: https://github.com/jaegertracing/jaeger-idl/blob/05fe64e9c305526901f70ff692030b388787e388/thrift/jaeger.thrift#L53 [trace-id-proto]: https://github.com/jaegertracing/jaeger-idl/blob/05fe64e9c305526901f70ff692030b388787e388/proto/api_v2/model.proto#L97 -## Do I need to run multiple collectors? +## 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? 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. These are NOT the reasons to run multiple instances: - * To avoid data loss. Jaeger drops data when the backend storage is not able to save it fast enough. Increasing the number of **jaeger-collector** instances, with more memory allocated to their internal queues, could provide a small, temporary relief, but does not remove the bottleneck of the storage backend. + * To avoid data loss. Jaeger drops data when the backend storage is not able to save it fast enough. Increasing the number of instances, with more memory allocated to their internal queues, could provide a small, temporary relief, but does not remove the bottleneck of the storage backend. ## How do I configure authentication for Jaeger UI diff --git a/content/docs/v2/_dev/operations/performance-tuning.md b/content/docs/v2/_dev/operations/performance-tuning.md index 83ff441e..00b1e8d9 100644 --- a/content/docs/v2/_dev/operations/performance-tuning.md +++ b/content/docs/v2/_dev/operations/performance-tuning.md @@ -12,11 +12,11 @@ Since Jaeger v2 is based on the OpenTelemetry Collector, most of the advice in t 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 +## Scale 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. +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. ## Make sure the storage can keep up @@ -25,14 +25,15 @@ Adding **jaeger-collector** instances is recommended when your platform provides The metric `jaeger_collector_save_latency_bucket` mentioned below is not yet available in Jaeger v2. {{< /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. ## Consider using Kafka as intermediate buffer -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-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. +Instances writing to Kafka can be scaled 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 instance can write to any partition. + +Instances consuming from Kafka (the ingester pipeline) 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 consumer instances than there are partitions in the Kafka topic, as in that case some instances will be idle. -**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. From 8ef2d79629bab89a8cf2b5f69402d1e7e4fb08bf Mon Sep 17 00:00:00 2001 From: Abhay Kumar Sonkar Date: Wed, 8 Jul 2026 19:17:45 +0530 Subject: [PATCH 2/6] fix(docs): remove stale jaeger-collector/ingester references from v2.19 docs Signed-off-by: Abhay Kumar Sonkar --- content/docs/v2/2.19/faq.md | 14 +++++------ .../v2/2.19/operations/performance-tuning.md | 25 ++++--------------- 2 files changed, 12 insertions(+), 27 deletions(-) diff --git a/content/docs/v2/2.19/faq.md b/content/docs/v2/2.19/faq.md index 2a8a4c67..0aaf7562 100644 --- a/content/docs/v2/2.19/faq.md +++ b/content/docs/v2/2.19/faq.md @@ -42,16 +42,16 @@ Under the hood, at the data model level, the Jaeger trace IDs are a sequence of [trace-id-thrift]: https://github.com/jaegertracing/jaeger-idl/blob/05fe64e9c305526901f70ff692030b388787e388/thrift/jaeger.thrift#L53 [trace-id-proto]: https://github.com/jaegertracing/jaeger-idl/blob/05fe64e9c305526901f70ff692030b388787e388/proto/api_v2/model.proto#L97 -## Do I need to run multiple collectors? +## 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? 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. These are NOT the reasons to run multiple instances: - * To avoid data loss. Jaeger drops data when the backend storage is not able to save it fast enough. Increasing the number of **jaeger-collector** instances, with more memory allocated to their internal queues, could provide a small, temporary relief, but does not remove the bottleneck of the storage backend. + * To avoid data loss. Jaeger drops data when the backend storage is not able to save it fast enough. Increasing the number of **jaeger** instances, with more memory allocated to their internal queues, could provide a small, temporary relief, but does not remove the bottleneck of the storage backend. ## How do I configure authentication for Jaeger UI @@ -61,6 +61,6 @@ For example, refer to this blog post for an example of [protecting Jaeger UI wit ## 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 diff --git a/content/docs/v2/2.19/operations/performance-tuning.md b/content/docs/v2/2.19/operations/performance-tuning.md index 83ff441e..12148e40 100644 --- a/content/docs/v2/2.19/operations/performance-tuning.md +++ b/content/docs/v2/2.19/operations/performance-tuning.md @@ -5,34 +5,19 @@ description: Tweaking your Jaeger instance to achieve a better performance aliases: [../performance-tuning] hasparent: true --- - 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. - +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. +Adding **jaeger** instances is recommended when your platform provides auto-scaling capabilities, or when it's easier to start/stop **jaeger** instances than changing existing, running instances. Scaling horizontally is also indicated when the CPU usage should be spread across nodes. ## Make sure the storage can keep up - {{< rawhtml >}}{{< /rawhtml >}} {{< danger >}} The metric `jaeger_collector_save_latency_bucket` mentioned below is not yet available in Jaeger v2. {{< /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 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. ## Consider using Kafka as intermediate buffer - -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. 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-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 From fa93ab612afb1022f6505ee2ce8940bad23bc503 Mon Sep 17 00:00:00 2001 From: Abhay Kumar Sonkar Date: Thu, 9 Jul 2026 00:31:40 +0530 Subject: [PATCH 3/6] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Abhay Kumar Sonkar --- content/docs/v2/2.19/operations/performance-tuning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/v2/2.19/operations/performance-tuning.md b/content/docs/v2/2.19/operations/performance-tuning.md index 12148e40..8d0d69c5 100644 --- a/content/docs/v2/2.19/operations/performance-tuning.md +++ b/content/docs/v2/2.19/operations/performance-tuning.md @@ -8,7 +8,7 @@ hasparent: true 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 +## 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. Adding **jaeger** instances is recommended when your platform provides auto-scaling capabilities, or when it's easier to start/stop **jaeger** instances than changing existing, running instances. Scaling horizontally is also indicated when the CPU usage should be spread across nodes. ## Make sure the storage can keep up From 4453b0fa1944ad02806079f37246b87450346e99 Mon Sep 17 00:00:00 2001 From: Abhay Kumar Sonkar Date: Thu, 9 Jul 2026 02:13:45 +0530 Subject: [PATCH 4/6] fix(docs): apply remaining collector-pipeline and grammar fixes from Copilot review Signed-off-by: Abhay Kumar Sonkar --- content/docs/v2/2.19/operations/performance-tuning.md | 7 ++++--- content/docs/v2/_dev/faq.md | 6 +++--- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/content/docs/v2/2.19/operations/performance-tuning.md b/content/docs/v2/2.19/operations/performance-tuning.md index 8d0d69c5..9c48848c 100644 --- a/content/docs/v2/2.19/operations/performance-tuning.md +++ b/content/docs/v2/2.19/operations/performance-tuning.md @@ -16,8 +16,9 @@ Adding **jaeger** instances is recommended when your platform provides auto-scal {{< danger >}} The metric `jaeger_collector_save_latency_bucket` mentioned below is not yet available in Jaeger v2. {{< /danger >}} -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. +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. ## Consider using Kafka as intermediate buffer -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 [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** 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 +Instances writing to Kafka can be scaled 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 instance can write to any partition. +Instances consuming from Kafka (the ingester pipeline) 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 consumer instances than there are partitions in the Kafka topic, as in that case some instances will be idle. \ No newline at end of file diff --git a/content/docs/v2/_dev/faq.md b/content/docs/v2/_dev/faq.md index 622f7ffe..ad570a54 100644 --- a/content/docs/v2/_dev/faq.md +++ b/content/docs/v2/_dev/faq.md @@ -44,7 +44,7 @@ Under the hood, at the data model level, the Jaeger trace IDs are a sequence of ## Do I need to run multiple instances? -> 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? +> 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 instance is not able to accept it fast enough. @@ -61,6 +61,6 @@ For example, refer to this blog post for an example of [protecting Jaeger UI wit ## 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 Jaeger's ingestion 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 From 1e74c764befcbeed7291fb7bd573fdecaa168fbc Mon Sep 17 00:00:00 2001 From: Abhay Kumar Sonkar Date: Thu, 9 Jul 2026 02:19:22 +0530 Subject: [PATCH 5/6] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Abhay Kumar Sonkar --- content/docs/v2/2.19/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/v2/2.19/faq.md b/content/docs/v2/2.19/faq.md index 0aaf7562..baaced7e 100644 --- a/content/docs/v2/2.19/faq.md +++ b/content/docs/v2/2.19/faq.md @@ -44,7 +44,7 @@ Under the hood, at the data model level, the Jaeger trace IDs are a sequence of ## Do I need to run multiple instances? -> 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? +> 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** instance is not able to accept it fast enough. From 74b79ba4645b0d8ac49b9bf16fc2a0d105e11dd5 Mon Sep 17 00:00:00 2001 From: Abhay Kumar Sonkar Date: Thu, 9 Jul 2026 02:35:05 +0530 Subject: [PATCH 6/6] fix(docs): address remaining Copilot review comments on v2.19 docs Signed-off-by: Abhay Kumar Sonkar --- content/docs/v2/2.19/faq.md | 4 ++-- .../v2/2.19/operations/performance-tuning.md | 18 ++++++++++++++++-- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/content/docs/v2/2.19/faq.md b/content/docs/v2/2.19/faq.md index 0aaf7562..13d99379 100644 --- a/content/docs/v2/2.19/faq.md +++ b/content/docs/v2/2.19/faq.md @@ -44,7 +44,7 @@ Under the hood, at the data model level, the Jaeger trace IDs are a sequence of ## Do I need to run multiple instances? -> 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? +> 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** instance is not able to accept it fast enough. @@ -61,6 +61,6 @@ For example, refer to this blog post for an example of [protecting Jaeger UI wit ## 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 the rest of the **jaeger** binary's pipeline? +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's ingestion 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 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 diff --git a/content/docs/v2/2.19/operations/performance-tuning.md b/content/docs/v2/2.19/operations/performance-tuning.md index 9c48848c..87afe46e 100644 --- a/content/docs/v2/2.19/operations/performance-tuning.md +++ b/content/docs/v2/2.19/operations/performance-tuning.md @@ -5,20 +5,34 @@ description: Tweaking your Jaeger instance to achieve a better performance aliases: [../performance-tuning] hasparent: true --- + 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 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. -Adding **jaeger** instances is recommended when your platform provides auto-scaling capabilities, or when it's easier to start/stop **jaeger** instances than changing existing, running instances. Scaling horizontally is also indicated when the CPU usage should be spread across nodes. + +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. + +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. + ## Make sure the storage can keep up + {{< rawhtml >}}{{< /rawhtml >}} {{< danger >}} The metric `jaeger_collector_save_latency_bucket` mentioned below is not yet available in Jaeger v2. {{< /danger >}} + 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. + ## Consider using Kafka as intermediate buffer + 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. + Instances writing to Kafka can be scaled 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 instance can write to any partition. + Instances consuming from Kafka (the ingester pipeline) 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 consumer instances than there are partitions in the Kafka topic, as in that case some instances will be idle. \ No newline at end of file