仪器

使用标准工具和自定义工具收集测量数据

一个工具在<.style data-emotion="css 154yii">.css-154yii{-webkit-text-decoration:underline;text-decoration:underline;text-decoration-style:dotted;text-decoration-thickness:1.5px;text-decoration-color:var(--chakra-colors-gray-300);text-underline-offset:0.2em;}.css-154yii:hover,.css-154yii[data-hover]{cursor:help;}.chakra-ui-dark .css-154yii:not([data-theme]),[data-theme=dark] .css-154yii:not([data-theme]),.css-154yii[data-theme=dark]{text-decoration-color:var(--chakra-colors-blue-400);}路由器收集数据并向后端指标报告测量结果。支持的工具包括来自OpenTelemetry的标准工具、路由器请求生命周期的标准工具和自定义工具。支持的仪器类型包括计数器和直方图。

您可以在router.yaml中配置工具，使用telemetry.instrumentation.instruments。

OpenTelemetry标准工具

OpenTelemetry指定了多个标准指标工具，这些工具在：路由器：

在路由器服务：
- http.server.active_requests - 正在传输的活动请求数。
- http.server.request.body.size - 路由器处理的请求请求体大小的直方图。
- http.server.request.duration - 路由器处理的请求持续时间的直方图。
在子图服务：
- http.client.request.body.size - 子图处理的请求请求体大小的直方图。
- http.client.request.duration - 子图处理的请求持续时间的直方图。
- http.client.response.body.size - 子图处理的请求响应体大小的直方图。

这些工具可以在router.yaml中进行配置：

router.yaml

1
telemetry:
2
  instrumentation:
3
    instruments:
4
      router:
5
        http.server.active_requests: true # (default false)
6
        http.server.request.body.size: true # (default false)
7
        http.server.request.duration: true # (default false)
8
      subgraph:
9
        http.client.request.body.size: true # (default false)
10
        http.client.request.duration: true # (default false)
11
        http.client.response.body.size: true # (default false)

它们可以通过添加或删除属性进行自定义。有关配置属性的更多信息，请参阅属性。

router.yaml

1
telemetry:
2
  instrumentation:
3
    instruments:
4
      default_requirement_level: required
5
      router:
6
        http.server.active_requests: 
7
          attributes:
8
            http.request.method: true
9
      subgraph:
10
        http.client.request.duration:
11
          attributes:
12
            subgraph.name: true

Apollo标准工具

了解 Apollo 提供的标准指标工具，见路由器's 请求生命周期，请参阅路由器工具。

自定义工具

此功能仅适用于 GraphOS 专用或企业版计划。
要比较所有计划类型对 GraphOS 功能的支持，请参阅价格页面.

您可以在路由器、supergraph 和子图服务中定义自定义工具。您还可以为路由器返回给客户端的响应数据中的每个 JSON 元素定义自定义工具。

以下示例配置定义了四个自定义工具

acme.request.duration 在 路由器 服务上
acme.graphql.requests 在 supergraph 服务上
acme.graphql.subgraph.errors 在 子图 服务上
acme.graphql.list.lengths 在每个返回给客户端的 JSON 元素上（定义在 graphql）

router.yaml

1
telemetry:
2
  instrumentation:
3
    instruments:
4
      router:
5
        http.server.active_requests: true
6
        acme.request.duration:
7
          value: duration
8
          type: counter
9
          unit: kb
10
          description: "my description"
11
          condition:
12
            eq:
13
              - 200
14
              - response_status: code
15
          attributes:
16
            http.response.status_code: true
17
            "my_attribute":
18
              response_header: "x-my-header"
19
  
20
      supergraph:
21
        acme.graphql.requests:
22
          value: unit
23
          type: counter
24
          unit: count
25
          description: "supergraph requests"
26
          
27
      subgraph:
28
        acme.graphql.subgraph.errors:
29
          value: unit
30
          type: counter
31
          unit: count
32
          description: "my description"
33

34
      graphql:
35
        acme.graphql.list.lengths:
36
          value:
37
            list_length: value
38
          type: histogram
39
          unit: count
40
          description: "my description"

ⓘ **注意**

请注意，您添加的遥测数据量可能会影响您路由器的性能。

自定义指标、事件和属性比标准指标消耗更多的处理资源。添加过多的（标准或自定义）可能会减慢您路由器的速度。
例如，events.*.request|error|response 之类的配置，该配置为所有路由器生命周期服务生成输出，应仅用于开发或调试，而不是用于生产。

对于正确记录的遥测数据，您应使用 info 级别的日志详细程度。设置 RUST_LOG 或 APOLLO_ROUTER_LOG 环境变量的值，以及 --log CLI 选项为 info。使用较简单的日志记录，如 error，可能会导致一些属性丢失。

工具命名约定

当定义自定义工具时，务必参考 OpenTelemetry (OTel) 语义约定。OTel 语义约定可以帮助您：

为何取名一个好的工具名称。
查看哪些标准属性可以附加到您的工具上。

一些需要特别注意的指导原则

不要在度量名称中包含单位名称。例如，size_kb 应该是 size 并且单位应该是 kb。
不要将_total作为后缀包含在内。例如，使用http.server.active_requests，而不是http.server.active_requests_total。
使用点表示法来在度量名称中分隔命名空间。例如，使用http.server.active_requests，而不是http_server_active_requests。

仪器配置

`default_requirement_level`

将default_requirement_level选项设置为要附加到默认标准仪器的默认属性，该属性由OpenTelemetry语义约定定义。

有效值

required（默认）- 默认情况下将附加必需属性到标准仪器。
recommended- 默认情况下将附加推荐属性到标准仪器。

router.yaml

1
telemetry:
2
  instrumentation:
3
    instruments:
4
      # Set the default requirement level
5
      default_requirement_level: required

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

router.yaml

1
telemetry:
2
  instrumentation:
3
    instruments:
4
      # Set the default requirement level
5
      default_requirement_level: required
6
      router:
7
        # Standard metrics
8
        http.server.request.body.size:
9
          attributes:
10
            # Standard attributes
11
            http.response.status_code: false
12
            # Custom attribute
13
            "acme.my_attribute":
14
              response_header: "x-my-header"
15
        # Standard metrics
16
        http.server.active_requests:
17
          attributes:
18
            # Standard attributes, different than other ones provides in standard metrics, custom attributes are not available on this standard metric
19
            http.request.method: false
20
            server.address: true
21
            server.port: true
22
            url.scheme: true

ⓘ **注意**

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

路由器请求生命周期服务

路由器请求生命周期有三个主要服务：

路由器服务- 处理尚未解析的传入请求。在不可见字节的上下文中工作。
Supergraph服务- 在请求被解析后、发送到subgraph之前处理请求。在GraphQL上下文中工作。
Subgraph服务- 在请求发送到subgraph之后处理请求。在GraphQL上下文中工作。

此外，您可以为每个返回给客户端的JSON元素定义graphql上的仪器。

要定义自定义仪器，请向router.yaml中添加新的密钥，作为telemetry.instruments.<service>.<custom-instrument>。例如，添加自定义仪器acme.request.duration:

router.yaml

1
telemetry:
2
  instrumentation:
3
    instruments:
4
      router: 
5
        acme.request.duration: # The name of your custom instrument/metric
6
          value: duration
7
          type: counter
8
          unit: s
9
          description: "my description"

`值`

您在定义仪器时指定的服务确定其可能的值。

值	定义	可用服务
`duration`	管道服务的持续时间。	`router`, `supergraph`, `subgraph`
`单位`	管道服务执行次数。	`router`, `supergraph`, `subgraph`, `graphql`
`自定义`	从管道服务中提取的自定义值。有关更多信息，请参阅选择器。	`router`, `supergraph`, `subgraph`, `graphql`
`event_duration`	管道服务中事件持续时间。	`supergraph`
`event_unit`	管道服务中事件执行的次数。	`supergraph`
`event_custom`	从管道服务事件中提取的自定义值。有关更多信息，请参阅选择器。	`supergraph`

ⓘ **注意**

event_*在使用supergraph响应体（response_data和response_errors）上的选择器时为强制性的。

可以通过自定义属性从管道中提取自定义指标值。例如，要计算请求头的内容的总和，创建一个计数器，其值设置为请求头

future.router.yaml

1
telemetry:
2
  instrumentation:
3
    instruments:
4
      router:
5
        acme.metric:
6
          # ...
7
          type: counter
8
          value:
9
           request_header: "x-my-header"

ⓘ **注意**

该值必须为仪器预期的类型。例如，计数器必须具有数值。

`type`

仪器有两种不同类型

counter - 单调计数器。例如，已处理的请求、完成的任务或发生的错误。
histogram - 值直方图。例如，请求持续时间或响应体大小。

future.router.yaml

1
telemetry:
2
  instrumentation:
3
    instruments:
4
      router:
5
        acme.metric: 
6
          # ...
7
          type: counter # counter, histogram

`单位`

在您的APM中显示的免费格式单位。

推荐使用unit和来自统一测量单位代码的SI单位及其定义。

future.router.yaml

1
telemetry:
2
  instrumentation:
3
    instruments:
4
      router:
5
        acme.metric: 
6
          # ...
7
          unit: s # seconds

`description`

将显示在您的APM中的仪器的免费格式描述。

future.router.yaml

1
telemetry:
2
  instrumentation:
3
    instruments:
4
      router:
5
        acme.metric: 
6
          # ...
7
          description: "my description"

`condition`

您可能只希望在特定条件下修改仪器。例如，您可能只希望在响应状态码为200时增加计数器。

为此请使用条件

future.router.yaml

1
telemetry:
2
  instrumentation:
3
    instruments:
4
      router:
5
        acme.metric:
6
          # ...
7
          condition:
8
            eq:
9
              - 200
10
              - response_status: code

`attributes`

仪器可以附有来自router管道的属性。这些属性用于在您的APM中过滤和组合指标。

属性可能来自标准属性或选择器，但不是标准度量http.server.active_requests。

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

router.yaml

1
telemetry:
2
  instrumentation:
3
    instruments:
4
      router:
5
        # Standard metrics
6
        http.server.request.body.size:
7
          attributes:
8
            # Standard attributes
9
            http.response.status_code: false
10
            # Custom attribute
11
            "acme.my_attribute":
12
              response_header: "x-my-header"
13
        # Standard metrics
14
        http.server.active_requests:
15
          attributes:
16
            # Standard attributes, different than other ones provides in standard metrics, custom attributes are not available on this standard metric
17
            http.request.method: false
18
            server.address: true
19
            server.port: true
20
            url.scheme: true
21
        # Custom metric 
22
        acme.metric: 
23
          value: duration
24
          type: counter
25
          unit: s
26
          description: "my description"
27
          attributes:
28
            http.response.status_code: true
29
            "my_attribute":
30
              # ...
31
              response_header: "x-my-header"
32
      subgraph:
33
        requests.timeout:
34
          value: unit
35
          type: counter
36
          unit: request
37
          description: "subgraph requests containing subgraph timeout"
38
          attributes:
39
            subgraph.name: true
40
          condition:
41
            eq:
42
              - "request timed out"
43
              - error: reason
44

45
      graphql:
46
        acme.graphql.list.lengths:
47
          value:
48
            list_length: value
49
          type: histogram
50
          unit: count
51
          description: "my description"
52
          attributes:
53
            graphql.type.name: true

仪器配置参考

选项	值	默认值	描述
`<attribute-name>`			自定义属性名称。
`<instrument-name>`			自定义仪器名称。
`attributes`	标准属性或选择器		自定义仪器的属性。
`condition`	conditions		变换仪器的条件。
`default_requirement_level`	`required`\|`recommended`	`required`	默认属性需求级别。
`type`	`counter`\|`histogram`		自定义仪器名称。
`单位`			一个单位名称，例如 `By` 或 `{request}`。
`description`			自定义仪器的描述。
`值`	`unit`\|`duration`\|`<custom>`\|`event_unit`\|`event_duration`\|`event_custom`		仪器的值。

Zipkin

事件

仪器

使用标准工具和自定义工具收集测量数据

OpenTelemetry标准工具

Apollo标准工具

自定义工具

工具命名约定

仪器配置

`default_requirement_level`

路由器请求生命周期服务

`值`

`duration`

`单位`

`自定义`

`event_duration`

`event_unit`

`event_custom`

`type`

`单位`

`description`

`condition`

`attributes`

仪器配置参考