Skip to content

[BUGFIX] Jaeger plugin: use the Jaeger API v3 to support Jaeger 2.21+ - #870

Open
AnKiT-GaRG2 wants to merge 2 commits into
perses:mainfrom
AnKiT-GaRG2:fix/jaeger-plugin-api-v3
Open

AnKiT-GaRG2 wants to merge 2 commits into
perses:mainfrom
AnKiT-GaRG2:fix/jaeger-plugin-api-v3

Conversation

@AnKiT-GaRG2

@AnKiT-GaRG2 AnKiT-GaRG2 commented Oct 12, 2026 •

Copy link
Copy Markdown

Description

Closes perses/perses#4560

The Jaeger datasource and trace query plugins call Jaeger's v1 query endpoints (/api/services, /api/operations, /api/traces, /api/traces/{id}). Jaeger removed them in 2.21. I ran the official jaegertracing/jaeger images and called the endpoints directly:

Jaeger /api/services /api/v3/services
2.10.0, 2.15.0, 2.20.0 200 200
2.21.0, 2.22.0 404 200

So against 2.21+ listing services and operations, searching traces and loading a trace all fail.

What changed

  • The client calls the API v3 endpoints (/api/v3/services, /api/v3/operations, /api/v3/traces, /api/v3/traces/{id}).
  • v3 returns OTLP JSON, so the old conversion from Jaeger's own span model (jaegerTraceToOTLP) and the v1 types are removed. Jaeger writes OTLP enums as numbers (kind: 2), so they are mapped to the names Perses uses (SPAN_KIND_SERVER, STATUS_CODE_ERROR, ...).
  • A v3 search returns the spans of all matching traces together, so they are grouped by trace id to build the search results (most recent trace first).
  • v3 needs both bounds of the start time. They come from the query's time range, or the last hour if there is none.
  • Search parameters are sent with both the camelCase names (Jaeger 2.20+) and the snake_case names (older 2.x), plus query.num_traces for the search depth, because a release ignores the names it does not know. Tags and span kind are sent as query.attributes (string values only).
  • Jaeger answers a search with no match with a 404 No traces found. That is now an empty result, any other failure is reported with Jaeger's message.
  • The default allowed endpoints of the proxy in the datasource editor are the v3 paths. README has a new "Compatibility" section.

Compatibility and migration

  • I ran the plugin code (client and getTraceData) against real Jaeger servers 2.10, 2.15, 2.16, 2.18, 2.20, 2.21 and 2.22: services, operations, search with operation/tags/duration filters, the result limit, and loading a trace by id all work on every one of them.
  • The span kind filter only works on Jaeger 2.20 and later. Older releases silently ignore it (the other filters are fine).
  • Existing datasources keep working. A datasource that goes through the Perses proxy and was saved with the old default allowed endpoints (/api/traces, /api/services, /api/operations) has its API v3 requests rejected by the proxy with a 403. In that case the client falls back to the API v1 for that datasource (and remembers it), converting the v1 traces to OTLP, so nothing changes for Jaeger 2.20 and older. The v1 code lives in legacy-api.ts and can be removed once the old endpoints are no longer worth supporting.
  • Against Jaeger 2.21+ a datasource with the old allowed endpoints cannot work, since Jaeger no longer serves the v1 API. The plugin then fails with a message asking to add GET /api/v3/traces, GET /api/v3/services and GET /api/v3/operations to the allowed endpoints (also in the README). I did not find a way to migrate saved datasources automatically. New datasources get the v3 paths by default.
  • I used [BUGFIX] since the plugin could not talk to current Jaeger releases at all, but please say if you would rather call it a BREAKINGCHANGE.
  • Jaeger v1 itself (the all-in-one 1.x binaries) is not covered by what I tested.

Screenshots

No visual change.

Checklist

  • Pull request has a descriptive title and context useful to a reviewer.
  • Pull request title follows the [<catalog_entry>] <commit message> naming convention using one of the
    following catalog_entry values: FEATURE, ENHANCEMENT, BUGFIX, BREAKINGCHANGE, DOC,IGNORE.
  • All commits have DCO signoffs.

UI Changes

  • Changes that impact the UI include screenshots and/or screencasts of the relevant changes.
  • Code follows the UI guidelines.
  • E2E tests are stable and unlikely to be flaky.
    See e2e docs for more details. Common issues include:
    • Is the data inconsistent? You need to mock API requests.
    • Does the time change? You need to use consistent time values or mock time utilities.
    • Does it have loading states? You need to wait for loading to complete.

Testing

In jaeger/: npm run type-check, npm run test (33 tests, the client and getTraceData tests are rewritten around the v3 responses, including a case with spans of several traces and services in one response, and the fallback for datasources with the old allowed endpoints) and oxlint (no new warnings) pass, and oxfmt --check is clean.

Not run: the repo-wide npm run lint/test, make checklicense, make checkdocs (needs Go and mdox, which I did not set up; no new files and no schema or Go SDK changes), and the Playwright e2e tests (I did not see any covering this plugin).

The fallback was also run against real Jaeger 2.20 (with a trace sent over OTLP) and 2.22 behind a fetch that answers 403 for /api/v3/*, like a proxy with the old allowed endpoints: on 2.20 services, operations, search and get-trace return correct OTLP (parent ids, kinds, status); on 2.22 the error message above is reported.

Jaeger 2.21 removed the v1 query endpoints (/api/services, /api/operations,
/api/traces), which the Jaeger datasource and trace query plugins called.
Against Jaeger 2.21 and later every request answers 404.

Call the API v3 endpoints instead. The v3 responses already use OTLP, so
the conversion from the Jaeger JSON model is replaced by a normalisation of
the OTLP enums, and the spans returned together for a search are grouped by
trace. Searches send the camelCase and snake_case parameter names so that
older 2.x releases keep working, and a search without a match is an empty
result instead of an error.

The default proxy endpoints of the datasource editor now allow the v3 paths.

Closes #4560 in perses/perses.

Signed-off-by: Ankit Garg <anki88520@gmail.com>
@AnKiT-GaRG2
AnKiT-GaRG2 requested a review from a team as a code owner October 12, 2026 07:33
@AnKiT-GaRG2
AnKiT-GaRG2 requested review from Gladorme and removed request for a team October 12, 2026 07:33
… with the former allowed endpoints

Signed-off-by: Ankit Garg <anki88520@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support Jaeger v2 in the Jaeger datasource plugin

1 participant