diff --git a/docs/en/latest/plugins/prometheus.md b/docs/en/latest/plugins/prometheus.md index 1c5c5300b994..b82738414e87 100644 --- a/docs/en/latest/plugins/prometheus.md +++ b/docs/en/latest/plugins/prometheus.md @@ -92,7 +92,7 @@ Reload APISIX for changes to take effect. | Name | Type | Required | Default | Valid values | Description | | ------------- | ------- | -------- | ------- | ------------ | ------------------------------------------ | -| `prefer_name` | boolean | | False | | If true, export Route/Service name instead of their ID in Prometheus metrics. | +| prefer_name | boolean | | False | | If true, export Route/Service name instead of their ID in Prometheus metrics. | ## Metrics diff --git a/docs/en/latest/plugins/zipkin.md b/docs/en/latest/plugins/zipkin.md index 3a4ec06dbc45..8ec64b052e9a 100644 --- a/docs/en/latest/plugins/zipkin.md +++ b/docs/en/latest/plugins/zipkin.md @@ -5,13 +5,13 @@ keywords: - API Gateway - Plugin - Zipkin -description: This document contains information about the Apache zipkin Plugin. +description: Zipkin is an open-source distributed tracing system. The zipkin Plugin instruments APISIX and sends traces to Zipkin based on the Zipkin API specification. --- -## Description + + + -[Zipkin](https://github.com/openzipkin/zipkin) is an open source distributed tracing system. The `zipkin` Plugin supports collecting and reporting traces to Zipkin collector based on the [Zipkin API specification](https://zipkin.io/pages/instrumenting.html). +## Description -It also works with [Apache SkyWalking](https://skywalking.apache.org/docs/main/latest/en/setup/backend/zipkin-trace/#zipkin-receiver) and [Jaeger](https://www.jaegertracing.io/docs/1.31/getting-started/#migrating-from-zipkin), both of which support Zipkin [v1](https://zipkin.io/zipkin-api/zipkin-api.yaml) and [v2](https://zipkin.io/zipkin-api/zipkin2-api.yaml) APIs. It can also work with other tracing systems adapted to Zipkin v1/v2 API format. +[Zipkin](https://github.com/openzipkin/zipkin) is an open-source distributed tracing system. The `zipkin` Plugin instruments APISIX and sends traces to Zipkin based on the [Zipkin API specification](https://zipkin.io/pages/instrumenting.html). -## Attributes +The Plugin can also send traces to other compatible collectors, such as [Jaeger](https://www.jaegertracing.io/docs/1.51/getting-started/#migrating-from-zipkin) and [Apache SkyWalking](https://skywalking.apache.org/docs/main/latest/en/setup/backend/zipkin-trace/#zipkin-receiver), both of which support Zipkin [v1](https://zipkin.io/zipkin-api/zipkin-api.yaml) and [v2](https://zipkin.io/zipkin-api/zipkin2-api.yaml) APIs. -| Name | Type | Required | Default | Valid values | Description | -|--------------|---------|----------|----------------|--------------|---------------------------------------------------------------------------------| -| endpoint | string | True | | | Zipkin HTTP endpoint. For example, `http://127.0.0.1:9411/api/v2/spans`. | -| sample_ratio | number | True | | [0.00001, 1] | How often to sample the requests. Setting to `1` will sample all requests. | -| service_name | string | False | "APISIX" | | Service name for the Zipkin reporter to be displayed in Zipkin. | -| server_addr | string | False | `$server_addr` | | IPv4 address for the Zipkin reporter. You can specify your external IP address. | -| span_version | integer | False | 2 | [1, 2] | Version of the span type. | +## Static Configurations -Each traced request will create the spans shown below: - -``` -request -├── proxy: from the beginning of the request to the beginning of header filter -└── response: from the beginning of header filter to the beginning of log -``` +By default, `zipkin` Plugin NGINX variables configuration is set to false in the [default configuration](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua): -For older versions (set `span_version` attribute to `1`), these spans are created: +To modify this value, add the updated configuration to `config.yaml`. For example: -``` -request -├── rewrite -├── access -└── proxy - └── body_filter +```yaml +plugin_attr: + zipkin: + set_ngx_var: true ``` -:::note +Reload APISIX for changes to take effect. -The span name doesn't represent the corresponding Nginx phase. +## Attributes -::: +See the configuration file for configuration options available to all Plugins. -### Sample code for upstream configuration +| Name | Type | Required | Default | Valid values | Description | +|--------------|---------|----------|----------------|--------------|---------------------------------------------------------------------------------| +| endpoint | string | True | | | Zipkin span endpoint to POST to, such as `http://127.0.0.1:9411/api/v2/spans`. | +|sample_ratio| number | True | | [0.00001, 1] | Frequency to sample requests. Setting to `1` means sampling every request. | +|service_name| string | False | "APISIX" | | Service name for the Zipkin reporter to be displayed in Zipkin. | +|server_addr | string | False |the value of `$server_addr` | IPv4 address | IPv4 address for the Zipkin reporter. For example, you can set this to your external IP address. | +|span_version | integer | False | 2 | [1, 2] | Version of the span type. | -```go title="Go with Gin" -func GetTracer(serviceName string, port int, enpoitUrl string, rate float64) *zipkin.Tracer { - // create a reporter to be used by the tracer - reporter := httpreporter.NewReporter(enpoitUrl) - // set-up the local endpoint for our service host is ip:host +## Examples - thisip, _ := GetLocalIP() +The examples below show different use cases of the `zipkin` Plugin. - host := fmt.Sprintf("%s:%d", thisip, port) - endpoint, _ := zipkin.NewEndpoint(serviceName, host) - // set-up our sampling strategy - sampler, _ := zipkin.NewCountingSampler(rate) - // initialize the tracer - tracer, _ := zipkin.NewTracer( - reporter, - zipkin.WithLocalEndpoint(endpoint), - zipkin.WithSampler(sampler), - ) - return tracer -} +### Send Traces to Zipkin -func main(){ - r := gin.Default() +The following example demonstrates how to trace requests to a Route and send traces to Zipkin using [Zipkin API v2](https://zipkin.io/zipkin-api/zipkin2-api.yaml). You will also understand the differences between span version 2 and span version 1. - tracer := GetTracer(...) +Start a Zipkin instance in Docker: - // use middleware to extract parentID from http header that injected by APISIX - r.Use(func(c *gin.Context) { - span := this.Tracer.Extract(b3.ExtractHTTP(c.Request)) - childSpan := this.Tracer.StartSpan(spanName, zipkin.Parent(span)) - defer childSpan.Finish() - c.Next() - }) - -} +```shell +docker run -d --name zipkin -p 9411:9411 openzipkin/zipkin ``` -## Enable Plugin +Create a Route with `zipkin` and use the default span version 2. You should adjust the IP address as needed for the Zipkin HTTP endpoint, and configure the sample ratio to `1` to trace every request. -The example below enables the Plugin on a specific Route: +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "zipkin-tracing-route", + "uri": "/anything", + "plugins": { + "zipkin": { + "endpoint": "http://127.0.0.1:9411/api/v2/spans", + "sample_ratio": 1, + "span_version": 2 + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org": 1 + } + } + }' +``` -:::note -You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command: +Send a request to the Route: -```bash -admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g') +```shell +curl "http://127.0.0.1:9080/anything" ``` -::: +You should receive an `HTTP/1.1 200 OK` response similar to the following: -```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' +```json { - "methods": ["GET"], - "uri": "/index.html", - "plugins": { - "zipkin": { - "endpoint": "http://127.0.0.1:9411/api/v2/spans", - "sample_ratio": 1, - "service_name": "APISIX-IN-SG", - "server_addr": "192.168.3.50" - } - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } - } -}' + "args": {}, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/7.64.1", + "X-Amzn-Trace-Id": "Root=1-65af2926-497590027bcdb09e34752b78", + "X-B3-Parentspanid": "347dddedf73ec176", + "X-B3-Sampled": "1", + "X-B3-Spanid": "429afa01d0b0067c", + "X-B3-Traceid": "aea58f4b490766eccb08275acd52a13a", + "X-Forwarded-Host": "127.0.0.1" + }, + ... +} ``` - +![trace-from-request](https://static.api7.ai/uploads/2024/01/23/MaXhacYO_zipkin-run-query.png) -## Example usage +Click __Show__ to see more tracing details: -You need to have your Zipkin instance running. You can run Zipkin on Docker by running: +![v2-trace-spans](https://static.api7.ai/uploads/2024/01/23/3SmfFq9f_trace-details.png) -```shell -docker run -d -p 9411:9411 openzipkin/zipkin +Note that with span version 2, every traced request creates the following spans: + +```text +request +├── proxy +└── response ``` -Now, when you make requests, it will be updated in Zipkin: +where `proxy` represents the time from the beginning of the request to the beginning of `header_filter`, and `response` represents the time from the beginning of `header_filter` to the beginning of `log`. + +Now, update the Plugin on the Route to use span version 1: ```shell -curl http://127.0.0.1:9080/index.html +curl "http://127.0.0.1:9180/apisix/admin/routes/zipkin-tracing-route" -X PATCH \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "plugins": { + "zipkin": { + "span_version": 1 + } + } + }' ``` +Send another request to the Route: + ```shell -HTTP/1.1 200 OK -... +curl "http://127.0.0.1:9080/anything" ``` -You can then open up the Zipkin UI on your browser at [http://127.0.0.1:9411/zipkin](http://127.0.0.1:9411/zipkin): +In the Zipkin web UI, you should see a new trace with details similar to the following: -![zipkin web-ui](../../../assets/images/plugin/zipkin-1.jpg) +![v1-trace-spans](https://static.api7.ai/uploads/2024/01/23/OPw2sTPa_v1-trace-spans.png) -![zipkin web-ui list view](../../../assets/images/plugin/zipkin-2.jpg) +Note that with the older span version 1, every traced request creates the following spans: -### Reporting traces to Jaeger +```text +request +├── rewrite +├── access +└── proxy + └── body_filter +``` -The Plugin also supports reporting traces to Jaeger. First, you have to have Jaeger running. +### Send Traces to Jaeger -To run it on Docker: +The following example demonstrates how to trace requests to a Route and send traces to Jaeger. + +Start a Jaeger instance in Docker: ```shell docker run -d --name jaeger \ - -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \ + -e COLLECTOR_ZIPKIN_HOST_PORT=9411 \ -p 16686:16686 \ -p 9411:9411 \ - jaegertracing/all-in-one:1.31 + jaegertracing/all-in-one ``` -Similar to configuring for Zipkin, create a Route and enable the Plugin: +Create a Route with `zipkin`. Please adjust the IP address as needed for the Zipkin HTTP endpoint, and configure the sample ratio to `1` to trace every request. -``` -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "methods": ["GET"], - "uri": "/index.html", +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "kin-tracing-route", + "uri": "/anything", "plugins": { - "zipkin": { - "endpoint": "http://127.0.0.1:9411/api/v2/spans", - "sample_ratio": 1, - "service_name": "APISIX-IN-SG", - "server_addr": "192.168.3.50" - } + "kin": { + "endpoint": "http://127.0.0.1:9411/api/v2/spans", + "sample_ratio": 1 + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org": 1 + } } -}' + }' ``` -Now, when you make requests, it will be updated on Jaeger: +Send a request to the Route: ```shell -curl http://127.0.0.1:9080/index.html +curl "http://127.0.0.1:9080/anything" ``` -```shell -HTTP/1.1 200 OK -... -``` - -You can access the Jaeger UI to view the traces in endpoint [http://127.0.0.1:16686](http://127.0.0.1:16686): - -![jaeger web-ui](../../../assets/images/plugin/jaeger-1.png) +You should receive an `HTTP/1.1 200 OK` response. -![jaeger web-ui trace](../../../assets/images/plugin/jaeger-2.png) +Navigate to the Jaeger web UI at [http://127.0.0.1:16686](http://127.0.0.1:16686), select APISIX as the Service, and click __Find Traces__, you should see a trace corresponding to the request: -## Delete Plugin +![jaeger-traces](https://static.api7.ai/uploads/2024/01/23/X6QdLN3l_jaeger.png) -To remove the `zipkin` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. +Similarly, you should find more span details once you click into a trace: -```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "methods": ["GET"], - "uri": "/index.html", - "plugins": { - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } - } -}' -``` +![jaeger-details](https://static.api7.ai/uploads/2024/01/23/iP9fXI2A_jaeger-details.png) -## Variables +### Using Trace Variables in Logging -The following nginx variables are set by zipkin: +The following example demonstrates how to configure the `kin` Plugin to set the following built-in variables, which can be used in logger Plugins or access logs: -- `zipkin_context_traceparent` - [W3C trace context](https://www.w3.org/TR/trace-context/#trace-context-http-headers-format), e.g.: `00-0af7651916cd43dd8448eb211c80319c-b9c7c989f97918e1-01` -- `zipkin_trace_id` - Trace Id of the current span -- `zipkin_span_id` - Span Id of the current span +- `kin_context_traceparent`: [trace parent](https://www.w3.org/TR/trace-context/#trace-context-http-headers-format) ID +- `kin_trace_id`: trace ID of the current span +- `kin_span_id`: span ID of the current span -How to use variables? you have to add it to your configuration file (`conf/config.yaml`): +Update the configuration file as below. You can customize the access log format to use the `zipkin` Plugin variables, and set `zipkin` variables in the `set_ngx_var` field. -```yaml title="./conf/config.yaml" -http: +```yaml title="conf/config.yaml" +nginx_config: + http: enable_access_log: true - access_log: "/dev/stdout" - access_log_format: '{"time": "$time_iso8601","zipkin_context_traceparent": "$zipkin_context_traceparent","zipkin_trace_id": "$zipkin_trace_id","zipkin_span_id": "$zipkin_span_id","remote_addr": "$remote_addr","uri": "$uri"}' + access_log_format: '{"time": "$time_iso8601","zipkin_context_traceparent": "$zipkin_context_traceparent","zipkin_trace_id": "$zipkin_trace_id","zipkin_span_id": "$zipkin_span_id","remote_addr": "$remote_addr"}' access_log_format_escape: json -plugins: - - zipkin plugin_attr: zipkin: set_ngx_var: true ``` -You can also include a trace_id when printing logs +Reload APISIX for configuration changes to take effect. + +You should see access log entries similar to the following when you generate requests: -```print error log -log.error(ngx.ERR,ngx_var.zipkin_trace_id,"error message") +```text +{"time": "23/Jan/2024:06:28:00 +0000","zipkin_context_traceparent": "00-61bce33055c56f5b9bec75227befd142-13ff3c7370b29925-01","zipkin_trace_id": "61bce33055c56f5b9bec75227befd142","zipkin_span_id": "13ff3c7370b29925","remote_addr": "172.28.0.1"} ``` diff --git a/docs/zh/latest/plugins/prometheus.md b/docs/zh/latest/plugins/prometheus.md index 81f1df224c15..885ebb80e222 100644 --- a/docs/zh/latest/plugins/prometheus.md +++ b/docs/zh/latest/plugins/prometheus.md @@ -92,7 +92,7 @@ plugin_attr: | 名称 | 类型 | 必选项 | 默认值 | 描述 | | ------------ | --------| ------ | ------ | ----------------------------------------------------- | -|`prefer_name` | boolean | 否 | False | 当设置为 `true` 时，则在`prometheus` 指标中导出路由/服务名称而非它们的 `id`。 | +|prefer_name | boolean | 否 | False | 当设置为 `true` 时，则在`prometheus` 指标中导出路由/服务名称而非它们的 `id`。 | ## 指标 diff --git a/docs/zh/latest/plugins/zipkin.md b/docs/zh/latest/plugins/zipkin.md index cca58374229b..5e6488eefaf9 100644 --- a/docs/zh/latest/plugins/zipkin.md +++ b/docs/zh/latest/plugins/zipkin.md @@ -5,13 +5,13 @@ keywords: - API 网关 - Plugin - Zipkin -description: 本文介绍了关于 Apache APISIX zipkin 插件的基本信息及使用方法。 +description: Zipkin 是一个开源的分布式链路追踪系统。`zipkin` 插件为 APISIX 提供了追踪功能，并根据 Zipkin API 规范将追踪数据上报给 Zipkin。 --- + + + + ## 描述 -[Zipkin](https://github.com/openzipkin/zipkin) 是一个开源的分布调用链追踪系统。`zipkin` 插件基于 [Zipkin API 规范](https://zipkin.io/pages/instrumenting.html)，支持收集跟踪信息并上报给 Zipkin Collector。 +[Zipkin](https://github.com/openzipkin/zipkin) 是一个开源的分布式链路追踪系统。`zipkin` 插件为 APISIX 提供了追踪功能，并根据 [Zipkin API 规范](https://zipkin.io/pages/instrumenting.html) 将追踪数据上报给 Zipkin。 -该插件也支持 [Apache SkyWalking](https://skywalking.apache.org/docs/main/next/en/setup/backend/zipkin-trace/#zipkin-receiver) 和 [Jaeger](https://www.jaegertracing.io/docs/1.31/getting-started/#migrating-from-zipkin)，因为它们都支持了 Zipkin [v1](https://zipkin.io/zipkin-api/zipkin-api.yaml) 和 [v2](https://zipkin.io/zipkin-api/zipkin2-api.yaml) API。当然 `zipkin` 插件也可以与其他支持了 Zipkin v1 和 v2 API 格式的调用链追踪系统集成。 +该插件还支持将追踪数据发送到其他兼容的收集器，例如 [Jaeger](https://www.jaegertracing.io/docs/1.51/getting-started/#migrating-from-zipkin) 和 [Apache SkyWalking](https://skywalking.apache.org/docs/main/latest/en/setup/backend/zipkin-trace/#zipkin-receiver)，这两者都支持 Zipkin [v1](https://zipkin.io/zipkin-api/zipkin-api.yaml) 和 [v2](https://zipkin.io/zipkin-api/zipkin2-api.yaml) API。 -## 属性 +## 静态配置 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -| ------------ | ------ | ------ | ------------ | ------------ | -------------------------------------------------------------------- | -| endpoint | string | 是 | | | Zipkin 的 HTTP 节点。例如：`http://127.0.0.1:9411/api/v2/spans`。 | -| sample_ratio | number | 是 | | [0.00001, 1] | 对请求进行采样的比例。当设置为 `1` 时，将对所有请求进行采样。 | -| service_name | string | 否 | "APISIX" | | 需要在 Zipkin 中显示的服务名称。 | -| server_addr | string | 否 | $server_addr | | 当前 APISIX 实例的 IPv4 地址。 | -| span_version | integer| 否 | 2 | [1, 2] | span 类型的版本。 | +默认情况下，`zipkin` 插件的 NGINX 变量配置在 [默认配置](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua) 中设置为 `false`： -在当前版本中，每个被跟踪的请求都会创建如下所示的 span： +要修改此值，请将更新后的配置添加到 `config.yaml` 中。例如： +```yaml +plugin_attr: + zipkin: + set_ngx_var: true ``` -request -├── proxy: from the beginning of the request to the beginning of header filter -└── response: from the beginning of header filter to the beginning of log -``` - -在旧版本（将 `span_version` 属性设置为 `1`）中，将创建如下 span： - -``` -request -├── rewrite -├── access -└── proxy - └── body_filter -``` - -:::note -上述 span 的名称与同名的 NGINX phase 没有联系。 +重新加载 APISIX 以使更改生效。 -::: +## 属性 -### 上游服务示例 +查看配置文件以获取所有插件可用的配置选项。 -```go title="Go with Gin" -func GetTracer(serviceName string, port int, enpoitUrl string, rate float64) *zipkin.Tracer { - // create a reporter to be used by the tracer - reporter := httpreporter.NewReporter(enpoitUrl) - // set-up the local endpoint for our service host is ip:host +| 名称 | 类型 | 是否必需 | 默认值 | 有效值 | 描述 | +|--------------|---------|----------|----------------|-------------|------------------| +| endpoint | string | 是 | | | 要 POST 的 Zipkin span 端点，例如 `http://127.0.0.1:9411/api/v2/spans`。 | +|sample_ratio| number | 是 | | [0.00001, 1] | 请求采样频率。设置为 `1` 表示对每个请求进行采样。 | +|service_name| string | 否 | "APISIX" | | 在 Zipkin 中显示的服务名称。 | +|server_addr | string | 否 | `$server_addr` 的值 | IPv4 地址 | Zipkin 报告器的 IPv4 地址。例如，可以将其设置为你的外部 IP 地址。 | +|span_version| integer | 否 | `2` | [1, 2] | span 类型的版本。 | - thisip, _ := GetLocalIP() +## 示例 - host := fmt.Sprintf("%s:%d", thisip, port) - endpoint, _ := zipkin.NewEndpoint(serviceName, host) - // set-up our sampling strategy - sampler, _ := zipkin.NewCountingSampler(rate) - // initialize the tracer - tracer, _ := zipkin.NewTracer( - reporter, - zipkin.WithLocalEndpoint(endpoint), - zipkin.WithSampler(sampler), - ) - return tracer -} +以下示例展示了使用 `zipkin` 插件的不同用例。 -func main(){ - r := gin.Default() +### 将追踪数据发送到 Zipkin - tracer := GetTracer(...) +以下示例演示了如何追踪对路由的请求，并将追踪数据发送到使用 [Zipkin API v2](https://zipkin.io/zipkin-api/zipkin2-api.yaml) 的 Zipkin。还将介绍 span 版本 2 和 版本 1 之间的区别。 - // use middleware to extract parentID from http header that injected by APISIX - r.Use(func(c *gin.Context) { - span := this.Tracer.Extract(b3.ExtractHTTP(c.Request)) - childSpan := this.Tracer.StartSpan(spanName, zipkin.Parent(span)) - defer childSpan.Finish() - c.Next() - }) +在 Docker 中启动一个 Zipkin 实例： -} +```shell +docker run -d --name zipkin -p 9411:9411 openzipkin/zipkin ``` -## 启用插件 +创建一条路由，开启 `zipkin` 插件，并使用其默认的 `span_version`，即 `2`。同时请根据需要调整 Zipkin HTTP 端点的 IP 地址，将采样比率配置为 `1` 以追踪每个请求。 -以下示例展示了如何在指定路由中启用 `zipkin` 插件： - -:::note +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "zipkin-tracing-route", + "uri": "/anything", + "plugins": { + "zipkin": { + "endpoint": "http://127.0.0.1:9411/api/v2/spans", + "sample_ratio": 1, + "span_version": 2 + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org": 1 + } + } + }' +``` -您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量： +向路由发送请求： -```bash -admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g') +```shell +curl "http://127.0.0.1:9080/anything" ``` -::: +你应该收到一个类似于以下的 `HTTP/1.1 200 OK` 响应： -```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' +```json { - "methods": ["GET"], - "uri": "/index.html", - "plugins": { - "zipkin": { - "endpoint": "http://127.0.0.1:9411/api/v2/spans", - "sample_ratio": 1, - "service_name": "APISIX-IN-SG", - "server_addr": "192.168.3.50" - } - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } - } -}' + "args": {}, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/7.64.1", + "X-Amzn-Trace-Id": "Root=1-65af2926-497590027bcdb09e34752b78", + "X-B3-Parentspanid": "347dddedf73ec176", + "X-B3-Sampled": "1", + "X-B3-Spanid": "429afa01d0b0067c", + "X-B3-Traceid": "aea58f4b490766eccb08275acd52a13a", + "X-Forwarded-Host": "127.0.0.1" + }, + ... +} ``` - +![来自请求的追踪](https://static.api7.ai/uploads/2024/01/23/MaXhacYO_zipkin-run-query.png) -## 测试插件 +点击 __Show__ 查看更多 trace 细节： -首先你需要通过以下命令创建一个 Zipkin 实例： +![v2 trace span](https://static.api7.ai/uploads/2024/01/23/3SmfFq9f_trace-details.png) -``` -docker run -d -p 9411:9411 openzipkin/zipkin +请注意，使用 span 版本 2 时，每个被 trace 的请求会创建以下 span： + +```text +request +├── proxy +└── response ``` -接下来你可以通过以下命令发起请求，该请求记录会出现在 Zipkin 中： +其中 `proxy` 表示从请求开始到 `header_filter` 开始的时间，而 `response` 表示从 `header_filter` 开始到 `log` 开始的时间。 + +现在，更新路由上的插件以使用 span 版本 1： ```shell -curl http://127.0.0.1:9080/index.html +curl "http://127.0.0.1:9180/apisix/admin/routes/zipkin-tracing-route" -X PATCH \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "plugins": { + "zipkin": { + "span_version": 1 + } + } + }' ``` -``` -HTTP/1.1 200 OK -... +向路由发送另一个请求： + +```shell +curl "http://127.0.0.1:9080/anything" ``` -最后你可以在浏览器中输入 `http://127.0.0.1:9411/zipkin` 访问 Zipkin UI 查询 traces： +在 Zipkin Web UI 中，你应该看到一个具有以下细节的新 trace： -![zipkin web-ui](../../../assets/images/plugin/zipkin-1.jpg) +![v1 trace span](https://static.api7.ai/uploads/2024/01/23/OPw2sTPa_v1-trace-spans.png) -![zipkin web-ui list view](../../../assets/images/plugin/zipkin-2.jpg) +请注意，使用较旧的 span 版本 1 时，每个被追踪的请求会创建以下 span： -### 上报到 Jaeger +```text +request +├── rewrite +├── access +└── proxy + └── body_filter +``` -除了对接 Zipkin，该插件也支持将 traces 上报到 Jaeger。 +### 将追踪数据发送到 Jaeger -首先，请使用以下命令运行 Jaeger 后端服务： +以下示例演示了如何追踪对路由的请求并将追踪数据发送到 Jaeger。 -``` +在 Docker 中启动一个 Jaeger 实例： + +```shell docker run -d --name jaeger \ - -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \ + -e COLLECTOR_ZIPKIN_HOST_PORT=9411 \ -p 16686:16686 \ -p 9411:9411 \ - jaegertracing/all-in-one:1.31 + jaegertracing/all-in-one ``` -通过以下命令创建路由并启用插件： +创建一条路由并开启 `zipkin` 插件。请根据需要调整 Zipkin HTTP 端点的 IP 地址，并将采样比率配置为 `1` 以追踪每个请求。 ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "methods": ["GET"], - "uri": "/index.html", +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "zipkin-tracing-route", + "uri": "/anything", "plugins": { - "zipkin": { - "endpoint": "http://127.0.0.1:9411/api/v2/spans", - "sample_ratio": 1, - "service_name": "APISIX-IN-SG", - "server_addr": "192.168.3.50" - } + "zipkin": { + "endpoint": "http://127.0.0.1:9411/api/v2/spans", + "sample_ratio": 1 + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org": 1 + } } -}' + }' ``` -接下来你可以通过以下命令发起请求，该条请求记录将会出现在 Jaeger 中： +向路由发送请求： ```shell -curl http://127.0.0.1:9080/index.html +curl "http://127.0.0.1:9080/anything" ``` -``` -HTTP/1.1 200 OK -... -``` - -最后你可以在浏览器中输入 `http://127.0.0.1:16686` 访问 Jaeger UI 查看 traces： - -![jaeger web-ui](../../../assets/images/plugin/jaeger-1.png) +你应该收到一个 `HTTP/1.1 200 OK` 响应。 -![jaeger web-ui trace](../../../assets/images/plugin/jaeger-2.png) +导航到 Jaeger Web UI [http://127.0.0.1:16686](http://127.0.0.1:16686)，选择 APISIX 作为服务，并点击 __Find Traces__，您应该看到一个与请求对应的 trace： -## 删除插件 +![jaeger trace](https://static.api7.ai/uploads/2024/01/23/X6QdLN3l_jaeger.png) -当你需要禁用 `zipkin` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务： +同样地，一旦点击进入一个追踪，你应该会找到更多 span 细节： -```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "methods": ["GET"], - "uri": "/index.html", - "plugins": { - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } - } -}' -``` +![jaeger 细节](https://static.api7.ai/uploads/2024/01/23/iP9fXI2A_jaeger-details.png) -## 如何使用变量 +### 在日志中使用追踪变量 -以下`nginx`变量是由`zipkin` 设置的。 +以下示例演示了如何配置 `zipkin` 插件以设置以下内置变量，这些变量可以在日志插件或访问日志中使用： -- `zipkin_context_traceparent` - [W3C trace context](https://www.w3.org/TR/trace-context/#trace-context-http-headers-format), 例如：`00-0af7651916cd43dd8448eb211c80319c-b9c7c989f97918e1-01` -- `zipkin_trace_id` - 当前 span 的 trace_id -- `zipkin_span_id` - 当前 span 的 span_id +- `zipkin_context_traceparent`: [W3C trace context](https://www.w3.org/TR/trace-context/#trace-context-http-headers-format) +- `zipkin_trace_id`: 当前 span 的 trace_id +- `zipkin_span_id`: 当前 span 的 span_id -如何使用？你需要在配置文件（`./conf/config.yaml`）设置如下： +按照以下方式更新配置文件。你可以自定义访问日志格式以使用 `zipkin` 插件变量，并在 `set_ngx_var` 字段中设置 `zipkin` 变量。 -```yaml title="./conf/config.yaml" -http: +```yaml title="conf/config.yaml" +nginx_config: + http: enable_access_log: true - access_log: "/dev/stdout" - access_log_format: '{"time": "$time_iso8601","zipkin_context_traceparent": "$zipkin_context_traceparent","zipkin_trace_id": "$zipkin_trace_id","zipkin_span_id": "$zipkin_span_id","remote_addr": "$remote_addr","uri": "$uri"}' + access_log_format: '{"time": "$time_iso8601","zipkin_context_traceparent": "$zipkin_context_traceparent","zipkin_trace_id": "$zipkin_trace_id","zipkin_span_id": "$zipkin_span_id","remote_addr": "$remote_addr"}' access_log_format_escape: json -plugins: - - zipkin plugin_attr: zipkin: set_ngx_var: true ``` -你也可以在打印日志的时候带上 `trace_id` +重新加载 APISIX 以使配置更改生效。 + +当生成请求时，你应该看到类似的访问日志： -```print error log -log.error(ngx.ERR,ngx_var.zipkin_trace_id,"error message") +```text +{"time": "23/Jan/2024:06:28:00 +0000","zipkin_context_traceparent": "00-61bce33055c56f5b9bec75227befd142-13ff3c7370b29925-01","zipkin_trace_id": "61bce33055c56f5b9bec75227befd142","zipkin_span_id": "13ff3c7370b29925","remote_addr": "172.28.0.1"} ```