feat(jaeger): add regex support for tag search in /api/traces

[emamihe]

Describe Your Changes

This PR adds regex support for tag values when searching traces via the Jaeger /select/jaeger/api/traces endpoint.

Behavior:

• Tag values prefixed with ~ are treated as regex patterns.
• Tag values without ~ keep exact-match behavior.

Examples:

• tags={"http.status_code":"~^2"} – matches 200, 201, 2xx, etc.
• tags={"order_id":"~abc.*"} – matches values starting with "abc"
• tags={"key":"value"} – exact match (unchanged)

Implementation:

• Regex filters are built as LogsQL field:re("regex") and executed by the VictoriaLogs storage engine.
• The ~ prefix is stripped before passing the value to the regex engine.

Files changed:

• app/vtselect/traces/query/query.go – logic for tag values with ~ prefix
• docs/victoriatraces/querying/README.md – documentation and examples for the ~ prefix

Checklist

The following checks are mandatory:

• My change adheres to VictoriaMetrics contributing guidelines.
• My change adheres to VictoriaMetrics development goals.

---

Summary by cubic

Adds regex support for tag filters in the Jaeger /select/jaeger/api/traces endpoint. Prefix a tag value with ~ to use regex; non-prefixed values remain exact matches.

• New Features
  • ~ values translate to LogsQL field:re("...") with proper quoting and run by VictoriaLogs.
  • Docs updated (tags param note, JSON and Jaeger UI examples incl. multiple regex filters); changelog notes support for single-node and cluster vtselect; apptest adds match and no‑match cases.

^{Written for commit 963249e. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/victoriatraces/querying/README.md">

<violation number="1" location="docs/victoriatraces/querying/README.md:219">
P3: The docs now show two different formats for the `tags` query param (space-separated `key=value` vs JSON map). The backend only accepts JSON (`json.Unmarshal` on `tags`), so leaving the space‑separated instructions while adding JSON regex examples is misleading and can result in invalid requests. Please make the `tags` format consistent in the examples/description.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P3: The docs now show two different formats for the tags query param (space-separated key=value vs JSON map). The backend only accepts JSON (json.Unmarshal on tags), so leaving the space‑separated instructions while adding JSON regex examples is misleading and can result in invalid requests. Please make the tags format consistent in the examples/description.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/victoriatraces/querying/README.md, line 219:

<comment>The docs now show two different formats for the `tags` query param (space-separated `key=value` vs JSON map). The backend only accepts JSON (`json.Unmarshal` on `tags`), so leaving the space‑separated instructions while adding JSON regex examples is misleading and can result in invalid requests. Please make the `tags` format consistent in the examples/description.</comment>

<file context>
@@ -216,3 +216,4 @@ Some valid filter examples:
 - Multiple span attribute filters: `error=unset otel.scope.name=redis-manual`
 - Single resource attribute filter: `resource_attr:telemetry.sdk.language=go`
 - Span attribute and resource attribute filters: `span.kind=client resource_attr:os.type=linux`
+- Regex filter: prefix the value with `~` to match by regex, e.g. `{"order_id":"~abc.*"}` or `{"http.status_code":"~^2"}` for values starting with "2"
</file context>

[jiekun]

Hello. Sorry for the delay, I was back from the conference break. I’ve left some comments. If you don’t have time to make the changes, I can handle the follow-ups. Thanks!

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/victoriatraces/changelog/CHANGELOG.md">

<violation number="1" location="docs/victoriatraces/changelog/CHANGELOG.md:15">
P3: Changelog entry references mismatched PR number and URL (`#100` vs `/pull/116`), causing inaccurate provenance.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

[jiekun]

FYI I updated the changelog and apptest as well. These're required when implementing something new.

And I noticed that the inverted filter could be nice to have, too, as requested by #120. Since Jaeger frontend parses user input as JSON dict {"key": "value"}, the input key!=value would become {"key!": "value"}, so it seems to be possible to handle such in similar way.

As the current pull request has hang for long time I wish to merge it to the current iteration, and we can improve it later via new pull request.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 4 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (master@0119ce7). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
app/vtselect/traces/query/query.go	0.00%	4 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             master    #116   +/-   ##
========================================
  Coverage          ?   7.71%           
========================================
  Files             ?      61           
  Lines             ?    8832           
  Branches          ?       0           
========================================
  Hits              ?     681           
  Misses            ?    8056           
  Partials          ?      95           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[emamihe]

FYI I updated the changelog and apptest as well. These're required when implementing something new.

And I noticed that the inverted filter could be nice to have, too, as requested by #120. Since Jaeger frontend parses user input as JSON dict {"key": "value"}, the input key!=value would become {"key!": "value"}, so it seems to be possible to handle such in similar way.

As the current pull request has hang for long time I wish to merge it to the current iteration, and we can improve it later via new pull request.

I just sent a PR #137 in this regard, hope it helps :)

[jiekun]

For transparency, we had some discussion here about the LogsQL syntax re(%s) used in this pull request:

			if strings.HasPrefix(v, "~") {
				// ~ prefix forces regex (e.g. tags={"key":"~value.*"})
				qStr += fmt.Sprintf(`AND %q:re(%s) `, k, strconv.Quote(v[1:]))

I was told that this syntax was going to be deprecated, so it's not documented. In the future pull request I'm going to change it to ~ according to this doc.

@emamihe