Jaeger data source on Grafana Labs

Configure the Jaeger data source

Tue, 21 Apr 2026 19:02:31 +0000

Configure the Jaeger data source

This document explains how to configure the Jaeger data source in Grafana, including connection settings, authentication, trace correlation, and provisioning.

Before you begin

Before configuring the data source, ensure you have:

Grafana permissions: Organization administrator role
Jaeger instance: A running Jaeger instance with an accessible query endpoint (default: http://localhost:16686)

Add the data source

To add the Jaeger data source:

Click Connections in the left-side menu.
Click Add new connection.
Type Jaeger in the search bar.
Select Jaeger.
Click Add new data source.

Connection settings

Configure the basic connection options for the data source.

Setting	Description
Name	The name used to refer to the data source in panels and queries.
Default	Toggle to make this the default data source for new panels.
URL	The URL of your Jaeger instance, such as `http://localhost:16686`.

Authentication

The Jaeger data source supports the following authentication methods.

Basic authentication

To use basic authentication:

Select Basic auth from the drop-down.
Enter the User name.
Enter the Password.

Forward OAuth identity

Select Forward OAuth identity from the drop-down to forward the user’s upstream OAuth identity to the data source. This is useful when Jaeger is behind an authenticating proxy.

Custom headers

You can add custom HTTP headers to requests sent to the Jaeger instance. Use this to pass authorization tokens or other required headers.

To add custom headers, expand the Additional settings section and configure them under Custom HTTP headers.

TLS configuration

To configure TLS/mTLS for the connection, expand the Additional settings section and configure the following options:

Setting	Description
TLS client auth	Toggle to enable client certificate authentication.
With CA cert	Toggle to provide a custom CA certificate.
Skip TLS verify	Toggle to skip TLS certificate verification (testing only).
Server name	Server name for TLS certificate validation.

Private data source connect

Private data source connect - Only for Grafana Cloud users.

Note
This section is only visible when the Grafana instance has the secure SOCKS proxy feature enabled.

Private data source connect, or PDC, allows you to establish a private, secured connection between a Grafana Cloud instance, or stack, and data sources secured within a private network. Click the drop-down to locate the URL for PDC. For more information regarding Grafana PDC refer to Private data source connect (PDC) and Configure Grafana private data source connect (PDC) for instructions on setting up a PDC connection.

Click Manage private data source connect to open your PDC connection page and view your configuration details.

Trace to logs

The Trace to logs setting configures the trace to logs feature that links trace spans to related log entries.

Note
If you use Grafana Cloud, open a support ticket in the Cloud Portal to access this feature.

There are two ways to configure trace to logs:

Simple configuration: Use a default query with tag-based filtering.
Custom query: Write a query using template variable syntax to interpolate values from the trace or span.

Use a simple configuration

Select the target data source from the drop-down list.
Set Span start time shift and Span end time shift to widen or shift the time range if log timestamps don’t exactly match span timestamps.
Configure Tags to use in the logs query. Tags must be present in span attributes or resources for the link to appear. You can remap tag names if the target data source doesn’t allow dots in labels (for example, remap http.status to http_status).
Optionally, toggle on Filter by trace ID or Filter by span ID to further filter logs.

Configure a custom query

Select the target data source from the drop-down list.
Set Span start time shift and Span end time shift.
Optionally, configure Tags to map. Use the ${__tags} variable in your custom query to interpolate mapped tags. If you don’t map tags, you can still reference any span tag directly, such as method="${__span.tags.method}".
Toggle on Use custom query.
Write a custom query using the variables listed in this table. The link only appears when all variables resolve to non-empty values.

Variables for custom queries

To use a variable, wrap it in ${}. For example: ${__span.name}.

Variable	Description
__tags	Interpolates mapped tags as a label matcher string in the target data source syntax. Only includes tags present in the span.
__span.spanId	The ID of the span.
__span.traceId	The ID of the trace.
__span.duration	The duration of the span.
__span.name	The name of the span.
__span.tags	Namespace for span tags. Access a specific tag with `${__span.tags.version}`. For tags with dots, use `${__span.tags["http.status"]}`.
__trace.traceId	The ID of the trace.
__trace.duration	The duration of the trace.
__trace.name	The name of the trace.

Trace to logs settings

Setting	Description
Data source	The target logs data source. You can select Loki or Splunk logs data sources.
Span start time shift	Shifts the start time for the logs query based on the span’s start time. Use time units such as `5s`, `1m`, `3h`. Use negative values to extend to the past. Default: `0`.
Span end time shift	Shifts the end time for the logs query based on the span’s end time. Default: `0`.
Tags	Tags to use in the logs query. Default: `cluster`, `hostname`, `namespace`, `pod`, `service.name`, `service.namespace`.
Filter by trace ID	Toggles whether to append the trace ID to the logs query.
Filter by span ID	Toggles whether to append the span ID to the logs query.
Use custom query	Toggles the use of a custom query with variable interpolation.
Query	The custom query. Use variable interpolation to customize with values from the span.

Trace to metrics

The Trace to metrics setting lets you link trace spans to related metrics queries.

To configure trace to metrics:

Select the target metrics data source from the drop-down list.
Configure Tags to map span attributes to metric label names. For example, map k8s.pod to pod.
Create linked queries using the $__tags keyword to interpolate the mapped tags.

Setting	Description
Data source	The target metrics data source.
Tags	Maps span attribute names to metric label names. For example, map `k8s.pod` to `pod`. Use the `$__tags` keyword to interpolate tags in queries.

Each linked query consists of:

Link Label: (Optional) A descriptive label for the linked query.
Query: The query to run when navigating from a trace to the metrics data source. Use $__tags to interpolate tags. For example, the query requests_total{$__tags} with tags k8s.pod=pod and cluster produces requests_total{pod="nginx-554b9", cluster="us-east-1"}.

Node graph

The Node graph setting is located under Additional settings, which is collapsed by default. Expand the Additional settings section on the data source configuration page to access it.

The Node graph setting enables the Node Graph visualization, which is disabled by default.

When enabled, Grafana displays the Node Graph above the trace view, showing the relationships between services in the trace.

Span bar

The Span bar setting is located under Additional settings, which is collapsed by default. Expand the Additional settings section on the data source configuration page to access it.

The Span bar setting controls what additional information appears in the span bar row of the trace view.

Option	Description
None	Adds nothing to the span bar row.
Duration	(Default) Displays the span duration on the span bar row.
Tag	Displays a span tag value on the span bar row. Specify the tag key to use, such as `component`.

Trace ID time parameters

The Query Trace by ID with Time Params setting is located under Additional settings, which is collapsed by default. Expand the Additional settings section on the data source configuration page to access it.

The Enable Time Parameters toggle controls whether Grafana sends start and end time parameters when querying a trace by ID. Enable this if your Jaeger instance benefits from time-bounded trace lookups.

Verify the connection

Click Save & test to verify the data source connection. A successful test displays the message Data source is working.

If the test fails, refer to Troubleshoot Jaeger data source issues for help resolving common errors.

Provision the data source

You can define and configure the data source in YAML files as part of the Grafana provisioning system. For more information about provisioning, refer to Provisioning Grafana.

Provisioning example

apiVersion: 1

datasources:
  - name: Jaeger
    type: jaeger
    uid: jaeger-ds
    url: http://localhost:16686
    access: proxy
    basicAuth: true
    basicAuthUser: <USERNAME>
    isDefault: false
    jsonData:
      tracesToLogsV2:
        datasourceUid: 'loki'
        spanStartTimeShift: '1h'
        spanEndTimeShift: '-1h'
        tags:
          - key: 'job'
          - key: 'instance'
          - key: 'pod'
          - key: 'namespace'
        filterByTraceID: false
        filterBySpanID: false
        customQuery: true
        query: 'method="$${__span.tags.method}"'
      tracesToMetrics:
        datasourceUid: 'prom'
        spanStartTimeShift: '-2m'
        spanEndTimeShift: '2m'
        tags:
          - key: 'service.name'
            value: 'service'
          - key: 'job'
        queries:
          - name: 'Sample query'
            query: 'sum(rate(traces_spanmetrics_latency_bucket{$$__tags}[5m]))'
      nodeGraph:
        enabled: true
      traceIdTimeParams:
        enabled: true
      spanBar:
        type: 'Duration'
    secureJsonData:
      basicAuthPassword: <PASSWORD>

Replace <USERNAME> and <PASSWORD> with your Jaeger credentials.

Provision with Terraform

You can provision the Jaeger data source using Terraform with the Grafana Terraform provider.

For more information about provisioning resources with Terraform, refer to the Grafana as code using Terraform documentation.

Terraform example

The following example provisions a Jaeger data source:

terraform {
  required_providers {
    grafana = {
      source  = "grafana/grafana"
      version = ">= 2.0.0"
    }
  }
}

provider "grafana" {
  url  = "<YOUR_GRAFANA_URL>"
  auth = "<YOUR_SERVICE_ACCOUNT_TOKEN>"
}

resource "grafana_data_source" "jaeger" {
  type = "jaeger"
  name = "Jaeger"
  url  = "http://localhost:16686"

  json_data_encoded = jsonencode({
    nodeGraph = {
      enabled = true
    }
    traceIdTimeParams = {
      enabled = true
    }
    tracesToLogsV2 = {
      datasourceUid    = "loki"
      filterByTraceID  = true
      filterBySpanID   = false
      tags = [
        { key = "service.name", value = "service" },
        { key = "job" }
      ]
    }
  })
}

Terraform example with basic authentication

The following example provisions a Jaeger data source with basic authentication:

resource "grafana_data_source" "jaeger_auth" {
  type                = "jaeger"
  name                = "Jaeger"
  url                 = "http://localhost:16686"
  basic_auth_enabled  = true
  basic_auth_username = "<USERNAME>"

  json_data_encoded = jsonencode({
    nodeGraph = {
      enabled = true
    }
    traceIdTimeParams = {
      enabled = true
    }
  })

  secure_json_data_encoded = jsonencode({
    basicAuthPassword = "<PASSWORD>"
  })
}

Replace the following placeholders:

<YOUR_GRAFANA_URL>: Your Grafana instance URL (for example, https://your-org.grafana.net for Grafana Cloud)
<YOUR_SERVICE_ACCOUNT_TOKEN>: A service account token with data source permissions
<USERNAME>: The username for basic authentication
<PASSWORD>: The password for basic authentication

For all available configuration options, refer to the Grafana provider data source resource documentation.

Jaeger query editor

Tue, 21 Apr 2026 19:02:31 +0000

Jaeger query editor

This document explains how to use the Jaeger query editor to search for traces, query by trace ID, visualize service dependencies, and import trace files.

For general information about querying data sources in Grafana, refer to Query and transform data.

Before you begin

Ensure you have configured the Jaeger data source.
Verify the connection is working by clicking Save & test in the data source settings.

Query types

The Jaeger query editor supports the following query types:

Search: Find traces by service, operation, tags, and duration.
TraceID: Query a specific trace by its ID.
Dependency graph: Visualize service dependencies within a time range.
Import trace: Upload a JSON trace file for visualization.

Search for traces

To search for traces:

Select Search from the Query type selector.
Fill out the search form:

Field	Description
Service Name	Select a service from the drop-down list, or type to filter. Supports template variables.
Operation Name	Select an operation for the chosen service. Select All to query all operations. This field is disabled until you select a service.
Tags	Enter tags in `logfmt` format, such as `error=true db.statement="select * from User"`.
Min Duration	Filter traces with a duration greater than this value. Use formats like `1.2s`, `100ms`, or `500us`.
Max Duration	Filter traces with a duration less than this value. Use the same format as Min Duration.
Limit	Maximum number of traces to return.

Query by trace ID

To query a specific trace:

Select TraceID from the Query type selector.
Enter the trace ID into the Trace ID field.
Press Shift+Enter to run the query.

Visualize the dependency graph

The dependency graph query type displays service dependencies as a Node Graph. It shows how services communicate and the volume of calls between them.

To visualize the dependency graph:

Select Dependency graph from the Query type selector.
Set the dashboard time range to the period you want to analyze.
Run the query.

The dependency graph uses the dashboard time range to query the Jaeger /api/dependencies endpoint. Grafana displays the result as a Node Graph with:

Nodes: Each node represents a service.
Edges: Each edge represents calls between services, with the call count shown as the edge label.

Note
Your Jaeger instance must have dependency data available. If the graph is empty, verify that Jaeger is collecting and processing dependency information for the selected time range.

Import a trace

You can upload a JSON file that contains a single trace and visualize it in Grafana. If the file contains multiple traces, Grafana visualizes the first trace.

To import a trace:

Click Import trace in the query editor.
Select a JSON file in the Jaeger trace format.

Trace JSON example

The JSON file must follow the Jaeger trace format with a data array containing trace objects:

{
  "data": [
    {
      "traceID": "2ee9739529395e31",
      "spans": [
        {
          "traceID": "2ee9739529395e31",
          "spanID": "2ee9739529395e31",
          "flags": 1,
          "operationName": "CAS",
          "references": [],
          "startTime": 1616095319593196,
          "duration": 1004,
          "tags": [
            {
              "key": "sampler.type",
              "type": "string",
              "value": "const"
            }
          ],
          "logs": [],
          "processID": "p1",
          "warnings": null
        }
      ],
      "processes": {
        "p1": {
          "serviceName": "loki-all",
          "tags": [
            {
              "key": "jaeger.version",
              "type": "string",
              "value": "Go-2.25.0"
            }
          ]
        }
      },
      "warnings": null
    }
  ],
  "total": 0,
  "limit": 0,
  "offset": 0,
  "errors": null
}

Query data via gRPC endpoint (public preview)

Jaeger offers an alternative method for querying data that uses their gRPC service over HTTP. For detailed information about the API and setup requirements, refer to the Jaeger API documentation.

The following queries are supported through the gRPC endpoint:

Service search
Operation search
Trace ID search

To enable gRPC querying for Jaeger within Grafana, enable the jaegerEnableGrpcEndpoint feature flag. Grafana Cloud customers should contact support to request access and provide feedback on this feature.

Use template variables

The Jaeger query editor supports Grafana template variables for creating dynamic, reusable dashboards. You can use template variables in the following query fields:

Service Name
Operation Name
Trace ID
Tags
Min Duration
Max Duration

Use standard Grafana variable syntax such as $variable or ${variable} in these fields. For example, set Service Name to $service to let dashboard users select the service from a drop-down list.

Troubleshoot Jaeger data source issues

Tue, 21 Apr 2026 19:02:31 +0000

Troubleshoot Jaeger data source issues

This document provides solutions to common issues you may encounter when configuring or using the Jaeger data source. For configuration instructions, refer to Configure the Jaeger data source.

Connection errors

These errors occur when Grafana can’t reach the Jaeger instance.

“Connection refused” or timeout errors

Symptoms:

Save & test fails with a connection error
Queries fail with network errors
Service and operation drop-downs don’t load

Possible causes and solutions:

Cause	Solution
Jaeger isn’t running	Verify Jaeger is running and accessible at the configured URL.
Incorrect URL	Check the URL setting in the data source configuration. The default Jaeger query endpoint is `http://localhost:16686`.
Firewall blocking access	Ensure firewall rules allow traffic from the Grafana server to the Jaeger endpoint.
Network segmentation	For Grafana Cloud accessing private Jaeger instances, configure Private data source connect.

“request failed: 404 Not Found”

Symptoms:

Save & test returns a 404 error
Queries fail with “request failed” messages

Solutions:

Verify the Jaeger URL doesn’t include a trailing path such as /api. The correct URL is the base endpoint, for example http://localhost:16686.
Confirm the Jaeger query service is running and listening on the expected port.
If using a reverse proxy, verify the proxy forwards requests to the correct Jaeger endpoint.

TLS errors

Symptoms:

Certificate validation errors during Save & test
Errors mentioning x509 or certificate verification

Solutions:

Verify your TLS certificates are valid and not expired.
Ensure the CA certificate is configured in the data source Additional settings if using a private CA.
For testing, you can temporarily toggle on Skip TLS verify in the data source settings. Don’t use this in production.
Verify the Server name setting matches the certificate’s Common Name or Subject Alternative Name.

Timeout errors

Symptoms:

Queries take a long time then fail
Errors mention timeout

Solutions:

Increase the timeout value in Additional settings > Timeout.
Verify network latency between Grafana and Jaeger is acceptable.
Check that the Jaeger query service isn’t overloaded.

Authentication errors

These errors occur when credentials are invalid or missing.

“401 Unauthorized” or “403 Forbidden”

Symptoms:

Save & test fails with authorization errors
Queries return access denied messages
Services and operations don’t load in drop-downs

Possible causes and solutions:

Cause	Solution
Invalid credentials	Verify the User and Password values in the data source configuration.
Missing authentication	If Jaeger requires authentication, toggle on the appropriate auth method.
Incorrect custom headers	Verify custom header names and values in Additional settings.
OAuth forwarding issues	If using Forward OAuth identity, verify the upstream OAuth provider is configured correctly.

Query errors

These errors occur when executing queries against Jaeger.

“traceID is empty”

Symptoms:

The query fails with “traceID is empty” when using the TraceID query type

Solutions:

Enter a valid trace ID in the Trace ID field.
Verify the trace ID is a valid hexadecimal string.
If using a template variable, verify the variable resolves to a non-empty value.

No data in search results

Symptoms:

Search query returns no traces
The trace list is empty

Possible causes and solutions:

Cause	Solution
Time range doesn’t contain data	Expand the dashboard or Explore time range. Verify traces exist in Jaeger for the selected period.
Service or operation doesn’t exist	Verify the selected service and operation names match what’s in Jaeger.
Tags syntax error	Ensure tags use `logfmt` format: `error=true db.statement="select * from User"`.
Duration format error	Use supported duration formats: `1.2s`, `100ms`, `500us`.
Limit set too low	Increase the Limit value or leave it empty for the default.

“The JSON file uploaded is not in a valid Jaeger format”

Symptoms:

Importing a trace file fails with a format error

Solutions:

Verify the JSON file follows the Jaeger trace format with a data array at the root level.
Ensure the file contains at least one trace object in the data array.
Validate the JSON syntax using a JSON linter.

Expected format:

{
  "data": [
    {
      "traceID": "<TRACE_ID>",
      "spans": [...],
      "processes": {...}
    }
  ]
}

Dependency graph errors

These errors relate to the dependency graph query type.

Empty dependency graph

Symptoms:

The dependency graph query returns no nodes or edges
The Node Graph panel is empty

Possible causes and solutions:

Cause	Solution
No dependency data	Verify Jaeger is collecting and processing service dependency information.
Time range too narrow	Expand the dashboard time range. Dependencies are calculated over the selected period.
Jaeger storage backend	Some Jaeger storage backends may not support dependency queries. Refer to the Jaeger documentation for storage-specific details.

gRPC endpoint errors

These errors occur when using the gRPC query endpoint.

gRPC queries fail

Symptoms:

Queries don’t use the gRPC endpoint
Search, service, and operation queries still use the REST API

Solutions:

Verify the jaegerEnableGrpcEndpoint feature flag is enabled in Grafana. This feature is in public preview.
Grafana Cloud customers should contact support to request access.
Note that search and dependency graph queries currently use the REST endpoint even when the feature flag is enabled. Only service search, operation search, and trace ID queries use gRPC.

Enable debug logging

To capture detailed error information for troubleshooting:

Set the Grafana log level to debug in the configuration file:
ini
```
[log]
level = debug
```
Reproduce the issue.
Review logs in /var/log/grafana/grafana.log (or your configured log location).
Look for Jaeger-specific entries that include request URLs, response status codes, and error details.
Reset the log level to info after troubleshooting to avoid excessive log volume.

Get additional help

If you’ve tried the solutions in this document and still encounter issues:

Check the Grafana community forums for similar issues.
Review the Grafana GitHub issues for known bugs related to the Jaeger data source.
Refer to the Jaeger documentation for service-specific guidance.
Contact Grafana Support if you’re an Enterprise, Cloud Pro, or Cloud Advanced user.
When reporting issues, include:
- Grafana version
- Jaeger version
- Error messages (redact sensitive information)
- Steps to reproduce
- Relevant data source configuration (redact credentials)