Add search and filter telemetry sub-section to CLI overview#1121
Open
JamesNK wants to merge 3 commits into
Open
Add search and filter telemetry sub-section to CLI overview#1121JamesNK wants to merge 3 commits into
JamesNK wants to merge 3 commits into
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new "Search and filter telemetry" sub-section to the CLI overview page that documents the --search option for aspire logs and aspire otel logs/traces/spans, covering free-text matching, structured field:value qualifiers, custom attribute qualifiers, negation, and comparison operators.
Changes:
- Adds a sub-section under "Inspect runtime data" describing console log search semantics.
- Documents structured telemetry search syntax with field lists for logs and spans/traces, plus examples.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+208
to
+234
| The `--search` option filters output by matching text against log content and trace/span fields. Multiple words are AND'd—all fragments must match. Use `"quoted phrases"` for multi-word fragments. | ||
|
|
||
| #### Console logs (`aspire logs --search`) | ||
|
|
||
| Matches against log line text content and resource name. Only free-text is supported (no structured qualifiers). | ||
|
|
||
| ```bash title="Aspire CLI" | ||
| aspire logs redis --search "timeout" | ||
| aspire logs --follow --search "\"connection error\"" | ||
| ``` | ||
|
|
||
| #### Structured telemetry (`aspire otel logs/traces/spans --search`) | ||
|
|
||
| Supports free-text and structured qualifiers in a single query. Free-text matches against message, resource name, scope, trace/span IDs, severity/status, and all attribute keys/values. | ||
|
|
||
| Structured qualifiers filter on specific fields with `field:value` syntax: | ||
|
|
||
| - **Log fields:** `severity`, `resource`, `scope`, `message`, `trace-id`, `span-id`, `event` | ||
| - **Span/Trace fields:** `name`, `resource`, `scope`, `status`, `kind`, `trace-id`, `span-id`, `duration` | ||
| - **Custom attributes:** `@http.method:GET`, `@db.system:redis` | ||
| - **Negation:** `-severity:debug`, `-@db.system:redis` | ||
| - **Comparison:** `duration:>100`, `duration:>=50` | ||
|
|
||
| ```bash title="Aspire CLI" | ||
| aspire otel logs --search "severity:error \"connection failed\"" | ||
| aspire otel spans --search "@http.method:GET duration:>100 status:error" | ||
| aspire otel logs --search "resource:api -severity:debug" |
JamesNK
force-pushed
the
docs/cli-overview-search-filter
branch
3 times, most recently
from
d85549f to
434198f
Compare
Member
|
Hey @JamesNK, just double checking, but is this intentionally targeting main? I thought this was a 13.4 feature. |
JamesNK
force-pushed
the
docs/cli-overview-search-filter
branch
2 times, most recently
from
77f69c9 to
6485c61
Compare
JamesNK
requested review from
aaronpowell,
davidfowl,
eerhardt and
maddymontaquila
as code owners
JamesNK
force-pushed
the
docs/cli-overview-search-filter
branch
from
6485c61 to
6e44189
Compare
JamesNK
force-pushed
the
docs/cli-overview-search-filter
branch
from
6e44189 to
440a8d6
Compare
Member
Author
|
@IEvangelist Ready for review |
davidfowl
approved these changes
May 29, 2026
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.
Adds a new "Search and filter telemetry" sub-section under "Inspect runtime data" in the CLI overview page.
Documents the
--searchoption for both console logs (aspire logs) and structured telemetry (aspire otel logs/traces/spans), including:field:valuequalifiers for logs and spans/traces@attr:value)-field:value)duration:>100)Content based on https://github.com/microsoft/aspire-skills/blob/main/skills/aspire-monitoring/references/monitoring.md#filtering