跨度

将路由生命周期上下文添加到跟踪中

一个跨度会捕获处理请求和响应时所涉及的前置和后置信息，作为其通过路由的请求生命周期（管道）. 您可以在应用程序性能监控器（APM）中显示追踪信息时使用来自范围的信息。

范围配置

路由请求生命周期服务

A路由's请求生命周期包括三个主要服务：

路由服务 - 在请求被解析之前处理传入的请求。在透明字节的上下文中工作。
Supergraph服务 - 在请求被解析并且发送到子图之前处理请求。在GraphQL上下文中工作。
子图服务 - 在请求被发送到子图之后处理请求。在GraphQL上下文中工作。

的路由、supergraph和subgraph部分用于定义每个服务的自定义范围配置：

router.yaml

1
telemetry:
2
  instrumentation:
3
    spans:
4
      router: 
5
        attributes: {}
6
          # ...     
7
      supergraph: 
8
        attributes: {}
9
          # ...
10
      subgraph: 
11
        attributes: {}
12
          # ...

`属性`

范围可能从路由管道中附加属性。这些属性用于在您的APM中过滤和分组范围。

属性可以来自标准属性或选择器。

要自定义范围上的属性，需要GraphOS 专属或企业计划。

可用的属性取决于管道的服务。

desc.router.yaml

1
telemetry:
2
  instrumentation:
3
    spans:
4
      router:
5
        attributes:
6
          # Standard attributes
7
          http.response.status_code: true
8
          # Custom attributes
9
          "my_attribute":
10
            response_header: "x-my-header"

您还可以使用条件，在自定义属性上使用选择器。您只能在选择器的同一执行级别上设置条件。例如，如果您想从 request_header 设置属性，则不能在 response_header 上设置条件。

desc.router.yaml

1
telemetry:
2
  instrumentation:
3
    spans: 
4
      router: 
5
        attributes:    
6
          on_error: 
7
            response_status: reason
8
            condition:
9
              not:
10
                eq:
11
                - response_status: code
12
                - 200

`default_attribute_requirement_level`

将 default_attribute_requirement_level 选项设为要附加到跨度上的默认属性，属性定义参照 OpenTelemetry语义约定。

有效值

required（默认值）
recommended

router.yaml

1
telemetry:
2
  instrumentation:
3
    spans:
4
      # Set the default requirement level
5
      default_attribute_requirement_level: required

属性可以单独配置，以便可以覆盖或禁用 required 属性。例如，可以单独设置 http.response.status_code 以覆盖标准值：

desc.router.yaml

1
telemetry:
2
  instrumentation:
3
    spans:
4
      # Set the default requirement level
5
      default_attribute_requirement_level: required
6
      router:
7
        attributes:
8
          # Disable standard attribute
9
          http.response.status_code: false

ⓘ 注意

OpenTelemetry规范定义的 opt-in 属性必须单独配置。

`mode`

将 mode 选项设为启用，则路由跨度会选择在路由中使用的旧属性，或OpenTelemetry规范中定义的属性。

有效值

spec_compliant
deprecated（默认值）

`spec_compliant`

此模式遵循OpenTelemetry规范。以前添加到未遵循约定的跨度的属性现在已删除。

使用此模式可能会提高性能，因为它减少了添加到跨度的属性数量。

router.yaml

1
telemetry:
2
  instrumentation:
3
    spans:
4
      mode: spec_compliant

目前这不是默认设置，但将在未来版本中实现。

`deprecated`

此模式是默认设置，如果未配置 mode 选项为 spec_compliant，则遵循先前行为。

router.yaml

1
telemetry:
2
  instrumentation:
3
    spans:
4
      mode: deprecated

属性添加到未遵循OpenTelemetry约定的跨度中。

ⓘ 注意

预计在未来的版本中，mode 选项将默认为 spec_compliant 并最终被移除。

跨度状态

默认情况下，只有当HTTP状态码不同于200时，跨度才会标记为错误。如果您想要将跨度的原因标记为错误，可以覆盖负责标记跨度是否错误的 otel.status_code 属性。如果出错，则 otel.status_code = error，否则为 ok。

命名

默认情况下，我们将使用与当前 OpenTelemetry 中 GraphQL 服务器语义约定兼容的 span 命名约定，这意味着根 span 名称必须采用以下格式 <graphql.operation.type> <graphql.operation.name>，前提是 graphql.operation.type 和 graphql.operation.name 都是可用的。

如果您想更改为每个服务创建的 span 的名称，可以通过使用任何您想要的选取器来覆盖此值，设置 otel.name 属性。

以下是一个示例，如果您想在 payload 中有一个 GraphQL 错误并且您希望将 router 和 supergraph span 标记为错误，同时希望将 router span 名称强制为 graphql_router。

router.yaml

1
telemetry:
2
  instrumentation:
3
    spans:
4
      router:
5
        attributes:
6
          otel.name:
7
            static: graphql_router # Override the span name to graphql_router 
8
          otel.status_code:
9
            static: error
10
            condition:
11
              eq:
12
              - true
13
              - on_graphql_error: true
14
      supergraph:
15
        attributes:
16
          otel.status_code:
17
            static: error
18
            condition:
19
              exists:
20
                response_errors: $[0].extensions.code # Here is an example to get the first error code, `on_graphql_error` is also available for supergraph

Span配置示例

以下是一个在 router.yaml 中设置 telemetry.spans 的示例，它为 router 服务的标准属性和自定义属性进行配置：

router.yaml

1
telemetry:
2
  instrumentation:
3
    spans:
4
      default_attribute_requirement_level: required
5
      mode: spec_compliant
6
      router:
7
        attributes:
8
          # Standard attributes (http)
9
          dd.trace_id: false
10
          http.request.body.size: false
11
          http.response.body.size: false
12
          http.request.method: false
13
          # ...
14
  
15
          # Conditional custom attribute
16
          otel.status_description: # You can conditionally put a status description attribute on your span if it respect the condition
17
            static: "there was an error"
18
            condition: # http response status code != 200 or it contains a graphql error in the payload
19
              any:
20
              - not:
21
                  eq:
22
                  - response_status: code
23
                  - 200
24
              - eq:
25
                - on_graphql_error
26
                - true
27
          # Custom attributes
28
          "acme.custom_1":
29
            trace_id: datadog
30
          "acme.custom_2":
31
            response_header: "X-CUSTOM2"
32
            default: "unknown"
33
          "acme.custom_3":
34
            env: "ENV_VAR"
35
          "static_attribute":
36
            static: "my_static_value"
37
            # ...
38
          
39
      supergraph:
40
        attributes: {}
41
          # ...
42
      subgraph:
43
        attributes: {}
44
          # ...

Spans配置引用

选项	值	默认	描述
`<attribute-name>`			自定义属性名称。
`属性`	标准属性\|选取器		span 的属性。
`条件`	条件		添加自定义属性的条件。
`default_attribute_requirement_level`	`required`\|`recommended`	`required`	默认属性要求级别。
`mode`	`spec_compliant` \| `deprecated`	`deprecated`	span 的属性。