diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-logs.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-logs.mdx index 2971234edf..a3b0ba7dfd 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-logs.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-logs.mdx @@ -73,9 +73,10 @@ The following options are available: | `"quoted phrase"` | Single fragment containing spaces | | `field:value` | Field qualifier — value must match the named field | | `-field:value` | Negated qualifier — excludes matches | + | `field:>value` / `field:>=value` / `field: @@ -133,6 +134,12 @@ The following options are available: aspire otel logs --search "scope:Microsoft.EntityFrameworkCore severity:Warning" ``` +- Filter logs by timestamp: + + ```bash title="Aspire CLI" + aspire otel logs --search "timestamp:>=2026-06-01T12:00:00 severity:error" + ``` + - View logs from a standalone dashboard using the login URL (token is automatically exchanged for an API key): ```bash title="Aspire CLI" diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-spans.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-spans.mdx index 595fa1c691..628a9c0ca9 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-spans.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-spans.mdx @@ -73,10 +73,10 @@ The following options are available: | `"quoted phrase"` | Single fragment containing spaces | | `field:value` | Field qualifier — value must match the named field | | `-field:value` | Negated qualifier — excludes matches | - | `field:>N` / `field:>=N` / `field:value` / `field:>=value` / `field: @@ -134,6 +134,12 @@ The following options are available: aspire otel spans --search "@db.system:postgresql" ``` +- Filter spans by timestamp: + + ```bash title="Aspire CLI" + aspire otel spans --search "timestamp:>=2026-03-01T08:30:00 kind:server" + ``` + - View spans from a standalone dashboard using the login URL (token is automatically exchanged for an API key): ```bash title="Aspire CLI" diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-traces.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-traces.mdx index 2e174409e0..27c4942767 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-traces.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-traces.mdx @@ -71,10 +71,10 @@ The following options are available: | `"quoted phrase"` | Single fragment containing spaces | | `field:value` | Field qualifier — value must match the named field | | `-field:value` | Negated qualifier — excludes matches | - | `field:>N` / `field:>=N` / `field:value` / `field:>=value` / `field: @@ -132,6 +132,12 @@ The following options are available: aspire otel traces --search "@http.status_code:500" ``` +- Filter traces by timestamp: + + ```bash title="Aspire CLI" + aspire otel traces --search "timestamp:>2026-01-15T09:30:00 status:error" + ``` + - View traces from a standalone dashboard using the login URL (token is automatically exchanged for an API key): ```bash title="Aspire CLI" diff --git a/src/frontend/src/content/docs/reference/cli/search-filter.mdx b/src/frontend/src/content/docs/reference/cli/search-filter.mdx index a9f4f514a1..3d667bb0d0 100644 --- a/src/frontend/src/content/docs/reference/cli/search-filter.mdx +++ b/src/frontend/src/content/docs/reference/cli/search-filter.mdx @@ -28,10 +28,28 @@ Search queries support free-text fragments, field qualifiers, attribute qualifie | `field:"value with spaces"` | Quoted field qualifier value | `message:"connection failed"` | | `@attr:value` | Attribute qualifier — matches custom span/log attributes | `@http.method:GET` | | `-field:value` / `-@attr:value` | Negated qualifier — excludes matches | `-severity:debug` | -| `field:>N` / `field:>=N` / `field:100` | +| `field:>value` / `field:>=value` / `field:100` | All terms are AND'd: every fragment and qualifier must independently match. +## Timestamp qualifier + +Use the `timestamp` field qualifier to narrow structured logs, traces, and spans to a specific date/time range. The qualifier accepts ISO 8601 date or date/time strings together with a comparison operator: + +```bash title="Aspire CLI" +aspire otel logs --search "timestamp:>2026-01-15T09:30:00" +aspire otel traces --search "timestamp:<=2026-06-01T12:00:00Z" +aspire otel spans --search "timestamp:>=2026-01-01 timestamp:<2027-01-01" +``` + +The supported comparison operators are `>`, `>=`, `<`, and `<=`. + +Timestamp values are internally stored with UTC. The `timestamp` value is converted to UTC using these timezone rules: + +- A value with no timezone suffix (for example `2026-01-15` or `2026-01-15T09:30:00`) is treated as local time on the dashboard server and adjusted to UTC before comparison. +- A value with a UTC offset (for example `2026-06-01T12:00:00+05:00`) is adjusted to UTC before comparison. +- A value with the `Z` suffix is treated as UTC directly. + ## Console logs Matches against log line text content and resource name. Only free-text is supported (no structured qualifiers). @@ -45,36 +63,39 @@ aspire logs --follow --search "\"connection error\"" Supports free-text and structured qualifiers. Free-text matches against message, resource name, scope, trace/span IDs, severity, and all attribute keys/values. -Available field qualifiers: `severity`, `resource`, `scope`, `message`, `trace-id`, `span-id`, `event`. +Available field qualifiers: `severity`, `resource`, `scope`, `message`, `trace-id`, `span-id`, `event`, `timestamp`. ```bash title="Aspire CLI" aspire otel logs --search "severity:error \"connection failed\"" aspire otel logs --search "resource:api -severity:debug" aspire otel logs --search "scope:Microsoft.EntityFrameworkCore" +aspire otel logs --search "timestamp:>=2026-06-01T12:00:00 severity:error" ``` ## Traces Supports free-text and structured qualifiers. Free-text matches against trace name, resource name, and all span fields within the trace. -Available field qualifiers: `name`, `resource`, `trace-id`, `status`, `duration`. +Available field qualifiers: `name`, `resource`, `trace-id`, `status`, `duration`, `timestamp`. ```bash title="Aspire CLI" aspire otel traces --search "checkout" aspire otel traces --search "status:error duration:>500" aspire otel traces --search "@http.status_code:500" +aspire otel traces --search "timestamp:>2026-01-15T09:30:00 status:error" ``` ## Spans Supports free-text and structured qualifiers. Free-text matches against span name, resource name, scope, trace/span IDs, status, kind, and all attribute keys/values. -Available field qualifiers: `name`, `resource`, `scope`, `status`, `kind`, `trace-id`, `span-id`, `duration`. +Available field qualifiers: `name`, `resource`, `scope`, `status`, `kind`, `trace-id`, `span-id`, `duration`, `timestamp`. ```bash title="Aspire CLI" aspire otel spans --search "@http.method:GET duration:>100 status:error" aspire otel spans --search "@db.system:postgresql" aspire otel spans --search "-kind:internal" +aspire otel spans --search "timestamp:>=2026-03-01T08:30:00 kind:server" ``` ## See also