cx-query-spans

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spans Query Skill

Spans 查询技能

Query and analyze distributed tracing data using the

cx spans

command with DataPrime syntax.

使用

cx spans

命令结合DataPrime语法查询和分析分布式追踪数据。

Understanding Spans in Coralogix

理解Coralogix中的Spans

Spans are the fundamental unit of tracing data. Traces are not stored as single entities - they are logical groupings of spans that share the same

traceID

. To analyze a trace, you query its constituent spans.

This means:

Metadata (
$m.*
) and labels (
$l.*
) are predictable - you can always filter on timestamp, duration, service name, and operation name without discovery.
User data (
$d.*
) contains trace identifiers (
```
traceID
```
,
```
spanID
```
,
```
parentSpanID
```
) and application-specific tags/attributes that vary by service. Always verify custom
```
$d
```
fields before assuming they exist.

Spans是追踪数据的基本单元。Traces不会作为单个实体存储——它们是共享同一

traceID

的Spans的逻辑分组。要分析一个trace，你需要查询其组成的Spans。

这意味着：

**元数据（
```
$m.*
```
）和标签（
```
$l.*
```
）**是可预测的——你无需进行发现操作，即可始终基于时间戳、时长、服务名称和操作名称进行过滤。
**用户数据（
```
$d.*
```
）**包含追踪标识符（
```
traceID
```
、
```
spanID
```
、
```
parentSpanID
```
）以及因服务而异的应用特定标签/属性。在假设自定义
```
$d
```
字段存在之前，务必先进行验证。

CLI Command

CLI命令

bash

cx spans '<dataprime_query>'

The

source spans

is automatically injected - do not include it in the query.

bash

cx spans '<dataprime_query>'

source spans

会自动注入——请勿在查询中包含它。

Options

选项

Flag	Default	Description
`--start`	`now-1h`	Start time (ISO 8601 or relative, e.g. `now-6h` )
`--end`	`now`	End time
`--limit`	`200`	Maximum number of results
`--tier`	`frequent`	Storage tier: `frequent` (hot/recent) or `archive` (cold/historical)
`-o, --output`	`text`	Output format: `text` , `json` , or `agents`

标志	默认值	描述
`--start`	`now-1h`	开始时间（ISO 8601格式或相对时间，例如 `now-6h` ）
`--end`	`now`	结束时间
`--limit`	`200`	最大结果数量
`--tier`	`frequent`	存储层级： `frequent` （热存储/近期数据）或 `archive` （冷存储/历史数据）
`-o, --output`	`text`	输出格式： `text` 、 `json` 或 `agents`

Span Data Model

Span数据模型

Standard Fields (Always Available)

标准字段（始终可用）

Field	Description
`$m.timestamp`	Span start timestamp
`$m.duration`	Span duration in microseconds (see Duration Units)
`$l.applicationName`	Application name - highest-level label. Meaning varies by customer (environment, team, region) but it always exists.
`$l.subsystemName`	Subsystem name - second-level label. Typically maps to a component.
`$l.serviceName`	Service name - the logical service unit emitting the span.
`$l.operationName`	Operation name - the span title (e.g. "POST /checkout", "db.query").
`$d.traceID`	Trace ID - groups spans into a single trace.
`$d.spanID`	Unique span identifier.
`$d.parentSpanID`	Parent span ID (empty string for root spans).
`$d.*`	Application-specific tags and attributes (see Field Discovery).

Note on label fields: The meaning of
$l.applicationName
and
$l.subsystemName
varies by customer - they may represent environments, teams, regions, or something else entirely. Don't assume what they map to. Use
cx search-fields
or sample queries to verify actual values.

字段	描述
`$m.timestamp`	Span开始时间戳
`$m.duration`	Span时长（单位为微秒，详见时长单位）
`$l.applicationName`	应用名称——最高层级的标签。其含义因客户而异（可能代表环境、团队、区域等），但始终存在。
`$l.subsystemName`	子系统名称——第二层级的标签。通常对应某个组件。
`$l.serviceName`	服务名称——生成Span的逻辑服务单元。
`$l.operationName`	操作名称——Span的标题（例如"POST /checkout"、"db.query"）。
`$d.traceID`	Trace ID——将Spans分组为单个trace。
`$d.spanID`	唯一的Span标识符。
`$d.parentSpanID`	父Span的ID（根Span为空字符串）。
`$d.*`	应用特定的标签和属性（详见字段发现）。

关于标签字段的说明：
$l.applicationName
和
$l.subsystemName
的含义因客户而异——它们可能代表环境、团队、区域或其他内容。不要假设它们的映射关系。使用
cx search-fields
或示例查询来验证实际值。

Duration Units

时长单位

$m.duration

is in microseconds:

500ms =
```
500000
```
1s =
```
1000000
```
1min =
```
60000000
```

When presenting duration values, always convert to human-readable units (milliseconds, seconds, or minutes) and include the unit. Never display raw microsecond values or the "µs" symbol.

dataprime

undefined

$m.duration

的单位是微秒：

500ms =
```
500000
```
1s =
```
1000000
```
1min =
```
60000000
```

在展示时长值时，务必转换为人类可读的单位（毫秒、秒或分钟）并标注单位。切勿显示原始微秒值或"µs"符号。

dataprime

undefined

Computed field for milliseconds

计算毫秒级时长字段

create latency_ms from $m.duration / 1000

undefined

create latency_ms from $m.duration / 1000

undefined

Error Detection

错误检测

Spans do not have a

$m.severity

field like logs. Errors are typically indicated by:

```
$d.tags.error == true
```
- the most common convention (OpenTelemetry/Jaeger)
Status codes in custom fields (e.g.
```
$d.http.status_code
```
,
```
$d.grpc.status_code
```
)
Other application-specific error tags

The exact field depends on the instrumentation library used. If

$d.tags.error

returns no results, inspect sample spans with

-o json

to discover how errors are tagged:

bash

cx spans "filter \$l.serviceName == 'api'" --limit 5 -o json

Spans不像日志那样拥有

$m.severity

字段。错误通常通过以下方式标识：

```
$d.tags.error == true
```
——最常见的约定（OpenTelemetry/Jaeger）
自定义字段中的状态码（例如
```
$d.http.status_code
```
、
```
$d.grpc.status_code
```
）
其他应用特定的错误标签

具体字段取决于所使用的工具库。如果

$d.tags.error

未返回结果，请使用

-o json

参数查看示例Span，以发现错误的标记方式：

bash

cx spans "filter \$l.serviceName == 'api'" --limit 5 -o json

Querying Spans

查询Spans

Essential Examples

基础示例

bash

undefined

bash

undefined

Get all spans for a trace

获取某个trace的所有Spans

cx spans "filter $d.traceID == '4f6a8f3c2e8a1b97'"

Find spans for a service

查找某个服务的Spans

cx spans "filter $l.serviceName == 'checkout-service'"

Find slow spans (> 1 second)

查找缓慢的Spans（时长>1秒）

cx spans 'filter $m.duration > 1000000'

Find error spans

查找错误Spans

cx spans 'filter $d.tags.error == true'

Aggregate latency by operation

按操作聚合延迟

cx spans 'groupby $l.operationName aggregate avg($m.duration) as avg_latency | orderby avg_latency desc'

Wider time range

更宽的时间范围

cx spans "filter $l.serviceName == 'api'" --start now-6h

undefined

cx spans "filter $l.serviceName == 'api'" --start now-6h

undefined

Wildfind Policy

Wildfind策略

Avoid
wildfind
by default. It scans all fields and is expensive.

The one exception: when the user provides a specific string and you don't know which field contains it:

bash

cx spans "wildfind 'connection refused'"

In all other cases, use

filter

with known fields or discover field names first with

cx search-fields

Tip:
wildfind
can also serve as a last-resort field discovery method - when
cx search-fields
doesn't find what you need, run
wildfind
with a known value, then inspect the matching spans to see which fields contain it.

默认情况下避免使用
wildfind
。它会扫描所有字段，开销很大。

唯一例外：当用户提供特定字符串，但你不知道该字符串存在于哪个字段时：

bash

cx spans "wildfind 'connection refused'"

在其他所有情况下，请使用

filter

结合已知字段，或先使用

cx search-fields

发现字段名称。

提示：
wildfind
也可以作为最后的字段发现方法——当
cx search-fields
找不到你需要的内容时，使用已知值运行
wildfind
，然后查看匹配的Spans，确认该值存在于哪些字段中。

Field Discovery

字段发现

Skip discovery when:

The query only uses standard fields (

$m.duration

$l.serviceName

$l.operationName

$d.traceID

)

The user explicitly names the fields they want
The fields have already been discovered earlier in the conversation

For customer-specific

$d.*

fields that need discovery, use one of these approaches:

无需进行发现操作的场景：

查询仅使用标准字段（

$m.duration

、

$l.serviceName

、

$l.operationName

、

$d.traceID

）

用户明确指定了他们需要的字段
字段已在对话前期完成发现

对于需要发现的客户特定

$d.*

字段，可使用以下方法之一：

1. Infer from Source Code (Preferred)

1. 从源代码推断（首选）

If you have access to the application's source code, examine OpenTelemetry instrumentation, span attribute definitions, and tracing middleware to identify field names directly.

如果你有权访问应用的源代码，请检查OpenTelemetry工具库、Span属性定义和追踪中间件，直接识别字段名称。

2. Semantic Search

2. 语义搜索

bash

cx search-fields "customer identifier" --dataset spans
cx search-fields "order ID" --dataset spans
cx search-fields "http response code" --dataset spans

Returns DataPrime paths with similarity scores. Note:

cx search-fields

only has access to the most common fields. If it doesn't find what you need, fall back to sample query inspection.

bash

cx search-fields "customer identifier" --dataset spans
cx search-fields "order ID" --dataset spans
cx search-fields "http response code" --dataset spans

返回带有相似度评分的DataPrime路径。注意：

cx search-fields

仅能访问最常见的字段。如果未找到所需内容，请回退到示例查询检查。

3. Sample Query Inspection

3. 示例查询检查

bash

cx spans "filter \$l.serviceName == 'api'" --limit 5 -o json

Inspect the JSON output to see all available fields in the actual data. This is especially useful for discovering fields in unstructured or deeply nested data that semantic search may not cover.

bash

cx spans "filter \$l.serviceName == 'api'" --limit 5 -o json

查看JSON输出，了解实际数据中的所有可用字段。这对于发现非结构化或深度嵌套数据中的字段尤为有用，这类字段可能无法被语义搜索覆盖。

Troubleshooting

故障排除

If a query returns no results, change one thing at a time:

Extend the time range:
```
--start now-6h
```
or
```
--start now-24h
```
Relax filters: remove the most restrictive condition
Check field availability: the field you're filtering by may only exist in a subset of spans - a span matching one filter may not have the field from another filter
Verify field names: run a sample query with
```
-o json
```
to inspect the actual schema
Check service names: service names are case-sensitive
Try archive tier:
```
--tier archive --start now-30d
```
for older data

如果查询未返回结果，请每次只修改一个因素：

扩展时间范围：使用
```
--start now-6h
```
或
```
--start now-24h
```
放宽过滤条件：移除最严格的条件
检查字段可用性：你过滤的字段可能仅存在于部分Spans中——匹配某个过滤条件的Span可能不包含另一个过滤条件中的字段
验证字段名称：运行带
```
-o json
```
参数的示例查询，检查实际的 schema
检查服务名称：服务名称区分大小写
尝试归档层级：对于较旧的数据，使用
```
--tier archive --start now-30d
```

References

参考资料

cx-dataprime
skill - Full query language reference: commands, operators, aggregations, text extraction, type conversions
Advanced Usage - Investigation workflows, common query patterns, latency analysis, trace debugging

For inline DataPrime help:

bash

cx dataprime list                  # List all commands and functions
cx dataprime show filter           # Detailed help for a specific command

cx-dataprime
技能——完整的查询语言参考：命令、运算符、聚合、文本提取、类型转换
高级用法——调查工作流、常见查询模式、延迟分析、trace调试

如需DataPrime内嵌帮助：

bash

cx dataprime list                  # 列出所有命令和函数
cx dataprime show filter           # 查看特定命令的详细帮助

cx-query-spans

Original

Translation

Spans Query Skill

Spans 查询技能

Understanding Spans in Coralogix

理解Coralogix中的Spans

CLI Command

CLI命令

Options

选项

Span Data Model

Span数据模型

Standard Fields (Always Available)

标准字段（始终可用）

Duration Units

时长单位

Computed field for milliseconds

计算毫秒级时长字段

Error Detection

错误检测

Querying Spans

查询Spans

Essential Examples

基础示例

Get all spans for a trace

获取某个trace的所有Spans

Find spans for a service

查找某个服务的Spans

Find slow spans (> 1 second)

查找缓慢的Spans（时长>1秒）

Find error spans

查找错误Spans

Aggregate latency by operation

按操作聚合延迟

Wider time range

更宽的时间范围

Wildfind Policy

Wildfind策略

Field Discovery

字段发现

1. Infer from Source Code (Preferred)

1. 从源代码推断（首选）

2. Semantic Search

2. 语义搜索

3. Sample Query Inspection

3. 示例查询检查

Troubleshooting

故障排除

References

参考资料

Related Skills

相关技能