You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by ju...@apache.org on 2022/05/20 16:26:40 UTC
[apisix] branch master updated: docs: update "Tracers" Plugins (#7086)
This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 9e0b27abc docs: update "Tracers" Plugins (#7086)
9e0b27abc is described below
commit 9e0b27abc02b3824b0e6006b9aa4f2d40663aea9
Author: Navendu Pottekkat <na...@gmail.com>
AuthorDate: Fri May 20 21:56:33 2022 +0530
docs: update "Tracers" Plugins (#7086)
Signed-off-by: Navendu Pottekkat <na...@gmail.com>
---
docs/en/latest/plugins/opentelemetry.md | 142 ++++++++++---------
docs/en/latest/plugins/skywalking.md | 240 ++++++++++++++++----------------
docs/en/latest/plugins/zipkin.md | 161 +++++++++++----------
3 files changed, 273 insertions(+), 270 deletions(-)
diff --git a/docs/en/latest/plugins/opentelemetry.md b/docs/en/latest/plugins/opentelemetry.md
index e56df790a..19eacf5ca 100644
--- a/docs/en/latest/plugins/opentelemetry.md
+++ b/docs/en/latest/plugins/opentelemetry.md
@@ -1,7 +1,12 @@
---
title: opentelemetry
+keywords:
+ - APISIX
+ - Plugin
+ - OpenTelemetry
+ - opentelemetry
+description: This document contains information about the Apache opentelemetry Plugin.
---
-
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
@@ -23,41 +28,76 @@ title: opentelemetry
## Description
-[OpenTelemetry](https://opentelemetry.io) report Tracing data according to [OpenTelemetry specification](https://opentelemetry.io/docs/reference/specification/).
-
-The plugin currently only supports binary-encoded OTLP over HTTP. For details, see [OTLP/HTTP].
+The `opentelemetry` Plugin can be used to report tracing data according to the [OpenTelemetry specification](https://opentelemetry.io/docs/reference/specification/).
-[OTLP/HTTP]: https://opentelemetry.io/docs/reference/specification/protocol/otlp/#otlphttp
+The Plugin only supports binary-encoded [OLTP over HTTP](https://opentelemetry.io/docs/reference/specification/protocol/otlp/#otlphttp).
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-| ------------ | ------ | ------ | -------- | ------------ | ----------------------------------------------------- |
-| sampler | object | optional | | | sampling config
-| sampler.name | string | optional | always_off | ["always_on", "always_off", "trace_id_ratio", "parent_base"] | sampling strategy，always_on：sampling all；always_off：sampling nothing；trace_id_ratio：base trace id percentage；parent_base：use parent decision, otherwise determined by root
-| sampler.options | object | optional | | {fraction = 0, root = {name = "always_off"}} | sampling strategy parameters
-| sampler.options.fraction | number | optional | 0 | [0, 1] | trace_id_ratio fraction
-| sampler.options.root | object | optional | {name = "always_off", options = {fraction = 0}} | | parent_base root sampler
-| sampler.options.root.name | string | optional | always_off | ["always_on", "always_off", "trace_id_ratio"] | sampling strategy
-| sampler.options.root.options | object | optional | {fraction = 0} | | sampling strategy parameters
-| sampler.options.root.options.fraction | number | optional | 0 | [0, 1] | trace_id_ratio fraction
-| additional_attributes | array[string] | optional | | | attributes (variable and its value) which will be appended to the trace span
-| additional_attributes[0] | string | required | | | APISIX or Nginx variable, like `http_header` or `route_id`
-
-## How To Enable
-
-First of all, enable the opentelemetry plugin in the `config.yaml`:
-
-```yaml
-# Add this in config.yaml
+| Name | Type | Required | Default | Valid values | Description |
+|---------------------------------------|---------------|----------|-------------------------------------------------|--------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| sampler | object | False | | | Sampling configuration. |
+| sampler.name | string | False | always_off | ["always_on", "always_off", "trace_id_ratio", "parent_base"] | Sampling strategy. `always_on`: always samples, `always_off`: never samples, `trace_id_ratio`: random sampling result based on given sampling probability, `parent_base`: use parent decision if given, else determined by the root sampler. |
+| sampler.options | object | False | | {fraction = 0, root = {name = "always_off"}} | Parameters for sampling strategy. |
+| sampler.options.fraction | number | False | 0 | [0, 1] | Sampling probability for `trace_id_ratio`. |
+| sampler.options.root | object | False | {name = "always_off", options = {fraction = 0}} | | Root sampler for `parent_base` strategy. |
+| sampler.options.root.name | string | False | always_off | ["always_on", "always_off", "trace_id_ratio"] | Root sampling strategy. |
+| sampler.options.root.options | object | False | {fraction = 0} | | Root sampling strategy parameters. |
+| sampler.options.root.options.fraction | number | False | 0 | [0, 1] | Root sampling probability for `trace_id_ratio`. |
+| additional_attributes | array[string] | False | | | Variables and its values which will be appended to the trace span. |
+| additional_attributes[0] | string | True | | | APISIX or Nginx variables. For example, `http_header` or `route_id`. |
+
+### Configuring the collector
+
+You can set up the collector by configuring it in you configuration file (`conf/config.yaml`):
+
+| Name | Type | Default | Description |
+|--------------------------------------------|---------|---------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| trace_id_source | enum | random | Source of the trace ID. Valid values are `random` or `x-request-id`. When set to `x-request-id`, the value of the `x-request-id` header will be used as trace ID. Make sure that is matches the regex pattern `[0-9a-f]{32}`. |
+| resource | object | | Additional [resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) appended to the trace. |
+| collector | object | {address = "127.0.0.1:4318", request_timeout = 3} | OpenTelemetry Collector configuration. |
+| collector.address | string | 127.0.0.1:4318 | Collector address. |
+| collector.request_timeout | integer | 3 | Report request timeout in seconds. |
+| collector.request_headers | object | | Report request HTTP headers. |
+| batch_span_processor | object | | Trace span processor. |
+| batch_span_processor.drop_on_queue_full | boolean | true | When set to `true`, drops the span when queue is full. Otherwise, force process batches. |
+| batch_span_processor.max_queue_size | integer | 2048 | Maximum queue size for buffering spans for delayed processing. |
+| batch_span_processor.batch_timeout | number | 5 | Maximum time in seconds for constructing a batch. |
+| batch_span_processor.max_export_batch_size | integer | 256 | Maximum number of spans to process in a single batch. |
+| batch_span_processor.inactive_timeout | number | 2 | Time interval in seconds between processing batches. |
+
+You can configure these as shown below:
+
+```yaml title="conf/config.yaml"
+plugin_attr:
+ opentelemetry:
+ resource:
+ service.name: APISIX
+ tenant.id: business_id
+ collector:
+ address: 192.168.8.211:4318
+ request_timeout: 3
+ request_headers:
+ foo: bar
+ batch_span_processor:
+ drop_on_queue_full: false
+ max_queue_size: 6
+ batch_timeout: 2
+ inactive_timeout: 1
+ max_export_batch_size: 2
+```
+
+## Enabling the Plugin
+
+To enable the Plugin, you have to add it to your configuration file (`conf/config.yaml`):
+
+```yaml title="conf/config.yaml"
plugins:
- - ... # plugin you need
+ - ...
- opentelemetry
```
-Then reload APISIX.
-
-Here's an example, enable the opentelemetry plugin on the specified route:
+Now, you can enable the Plugin on a specific Route:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -82,54 +122,12 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}'
```
-## How to set collecting
-
-You can set the collecting by specifying the configuration in `conf/config.yaml`.
-
-| Name | Type | Default | Description |
-| ------------ | ------ | -------- | ----------------------------------------------------- |
-| trace_id_source | enum | random | the source of trace id, the valid value is `random` or `x-request-id`. If `x-request-id` is set, the value of `x-request-id` request header will be used as trace id. Please make sure it match regex pattern `[0-9a-f]{32}` |
-| resource | object | | additional [resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) append to trace |
-| collector | object | {address = "127.0.0.1:4318", request_timeout = 3} | otlp collector |
-| collector.address | string | 127.0.0.1:4318 | collector address |
-| collector.request_timeout | integer | 3 | report request timeout(second) |
-| collector.request_headers | object | | report request http headers |
-| batch_span_processor | object | | trace span processor |
-| batch_span_processor.drop_on_queue_full | boolean | true | drop span when queue is full, otherwise force process batches |
-| batch_span_processor.max_queue_size | integer | 2048 | maximum queue size to buffer spans for delayed processing |
-| batch_span_processor.batch_timeout | number | 5 | maximum duration(second) for constructing a batch |
-| batch_span_processor.max_export_batch_size | integer | 256 | maximum number of spans to process in a single batch |
-| batch_span_processor.inactive_timeout | number | 2 | timer interval(second) for processing batches |
-
-Here is an example:
-
-```yaml
-plugin_attr:
- opentelemetry:
- resource:
- service.name: APISIX
- tenant.id: business_id
- collector:
- address: 192.168.8.211:4318
- request_timeout: 3
- request_headers:
- foo: bar
- batch_span_processor:
- drop_on_queue_full: false
- max_queue_size: 6
- batch_timeout: 2
- inactive_timeout: 1
- max_export_batch_size: 2
-```
-
## Disable Plugin
-When you want to disable the opentelemetry plugin on a route/service, it is very simple,
-you can delete the corresponding JSON configuration in the plugin configuration,
-no need to restart the service, it will take effect immediately:
+To disable the `opentelemetry` 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.
```console
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uris": [
diff --git a/docs/en/latest/plugins/skywalking.md b/docs/en/latest/plugins/skywalking.md
index 87876bc33..016f7cc29 100644
--- a/docs/en/latest/plugins/skywalking.md
+++ b/docs/en/latest/plugins/skywalking.md
@@ -1,7 +1,12 @@
---
title: skywalking
+keywords:
+ - APISIX
+ - Plugin
+ - SkyWalking
+ - skywalking
+description: This document contains information about the Apache skywalking Plugin.
---
-
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
@@ -23,30 +28,85 @@ title: skywalking
## Description
-[**SkyWalking**](https://github.com/apache/skywalking) uses its native Nginx LUA tracer to provide tracing, topology analysis, and metrics from service and URI perspective.
+The `skywalking` Plugin is used to integrate with [Apache SkyWalking](https://github.com/apache/skywalking).
+
+SkyWalking uses its native Nginx Lua tracer to provide tracing, topology analysis, and metrics from both service and URI perspectives.
-The SkyWalking server can support both HTTP and gRPC protocols. Currently, the APISIX client only supports the HTTP protocol.
+APISIX supports HTTP protocol to interact with the SkyWalking server.
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-| ------------ | ------ | ----------- | -------- | ------------ | -------------------------------------------------------------------- |
-| sample_ratio | number | required | 1 | [0.00001, 1] | the ratio of sampling |
+| Name | Type | Required | Default | Valid values | Description |
+|--------------|--------|----------|---------|--------------|----------------------------------------------------------------------------|
+| sample_ratio | number | True | 1 | [0.00001, 1] | How often to sample the requests. Setting to `1` will sample all requests. |
-## How To Enable
+### Configuring the endpoint
-First of all, enable the SkyWalking plugin in the `config.yaml`:
+You can configure these attributes on your configuration file (`conf/config.yaml`):
+| Name | Type | Default | Description |
+|-----------------------|---------|----------------------------------------|----------------------------------------------------------------------------------------------|
+| service_name | string | "APISIX" | Service name for SkyWalking reporter. |
+| service_instance_name | string | "APISIX Instance Name" | Service instance name for SkyWalking reporter. Set to `$hostname` to get the local hostname. |
+| endpoint_addr | string | "http://127.0.0.1:12800" | SkyWalking HTTP endpoint. For example, `http://127.0.0.1:12800`. |
+| report_interval | integer | Value in the SkyWalking client library | Reporting interval time in seconds. |
+
+You can configure these as shown below:
+
+```yaml title="conf/config.yaml"
+plugin_attr:
+ skywalking:
+ service_name: APISIX
+ service_instance_name: "APISIX Instance Name"
+ endpoint_addr: http://127.0.0.1:12800
```
-# Add this in config.yaml
+
+### Sample code for upstream configuration
+
+```java title="Java with Spring Boot"
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+import javax.servlet.http.HttpServletRequest;
+
+@RestController
+public class TestController {
+ @RequestMapping("/uid/{count}")
+ public String getUidList(@PathVariable("count") String countStr, HttpServletRequest request) {
+ return "OK";
+ }
+}
+```
+
+You can configure the SkyWalking agent while starting your service:
+
+```shell title="agent/config/agent.config"
+agent.service_name=yourservername
+collector.backend_service=10.110.149.175:11800
+```
+
+Then, run the script:
+
+```shell
+nohup java -javaagent:/root/skywalking/app/agent/skywalking-agent.jar \
+-jar /root/skywalking/app/app.jar \
+--server.port=8089 \
+2>&1 > /root/skywalking/app/logs/nohup.log &
+```
+
+## Enabling the Plugin
+
+To enable the Plugin, you have to add it to your configuration file (`conf/config.yaml`):
+
+```yaml title="conf/config.yaml"
plugins:
- - ... # plugin you need
+ - ...
- skywalking
```
-Then reload APISIX, a background timer will be created to report data to the SkyWalking OAP server.
+Once you do this, a background timer will be created to report data to the SkyWalking OAP server.
-Here's an example, enable the SkyWalking plugin on the specified route:
+Now, you can enable the Plugin on a specific Route:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -69,104 +129,80 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}'
```
-You also can complete the above operation through the web interface, first add a route, then add SkyWalking plugin:
-
-
+<!-- You also can complete the above operation through the web interface, first add a route, then add SkyWalking plugin:
-## How to set endpoint
+ -->
-We can set the endpoint by specifying the configuration in `conf/config.yaml`.
+## Example usage
-| Name | Type | Default | Description |
-| ------------ | ------ | -------- | -------------------------------------------------------------------- |
-| service_name | string | "APISIX" | service name for SkyWalking reporter |
-| service_instance_name | string |"APISIX Instance Name" | service instance name for SkyWalking reporter， set it to `$hostname` to get local hostname directly.|
-| endpoint_addr | string | "http://127.0.0.1:12800" | the HTTP endpoint of SkyWalking, for example: http://127.0.0.1:12800 |
-| report_interval | integer | use the value in the SkyWalking client library | the report interval, in seconds |
+First, you need to have your SkyWalking server running.
-Here is an example:
+You can run it on Docker by:
-```yaml
-plugin_attr:
- skywalking:
- service_name: APISIX
- service_instance_name: "APISIX Instance Name"
- endpoint_addr: http://127.0.0.1:12800
+```shell
+sudo docker run --name skywalking -d -p 1234:1234 -p 12800:12800 --restart always apache/skywalking-oap-server:8.7.0-es6
```
-## Test Plugin
+:::tip
-### Run SkyWalking Example
+By default, SkyWalking uses H2 storage. You can also use Elasticsearch storage instead.
-1. Start the SkyWalking OAP Server:
- - By default, SkyWalking uses H2 storage, start SkyWalking directly by
+First, install Elasticsearch. You can do it on Docker by running:
- ```shell
- sudo docker run --name skywalking -d -p 1234:1234 -p 12800:12800 --restart always apache/skywalking-oap-server:8.7.0-es6
- ```
+```shell
+sudo docker run -d --name elasticsearch -p 9200:9200 -p 9300:9300 --restart always -e "discovery.type=single-node" elasticsearch:6.7.2
+```
- - Of Course, you may want to use Elasticsearch storage instead
+Optionally, you can install Elasticsearch management page, elasticsearch-hq:
- 1. First, you should install Elasticsearch:
+```shell
+sudo docker run -d --name elastic-hq -p 5000:5000 --restart always elastichq/elasticsearch-hq
+```
- ```shell
- sudo docker run -d --name elasticsearch -p 9200:9200 -p 9300:9300 --restart always -e "discovery.type=single-node" elasticsearch:6.7.2
- ```
+Once you have Elasticsearch installed, you can start a SkyWalking server by running:
- 2. Optionally, you can install ElasticSearch management page: elasticsearch-hq
+```shell
+sudo docker run --name skywalking -d -p 1234:1234 -p 12800:12800 --restart always --link elasticsearch:elasticsearch -e SW_STORAGE=elasticsearch -e SW_STORAGE_ES_CLUSTER_NODES=elasticsearch:9200 apache/skywalking-oap-server:8.7.0-es6
+```
- ```shell
- sudo docker run -d --name elastic-hq -p 5000:5000 --restart always elastichq/elasticsearch-hq
- ```
+:::
- 3. Finally, run SkyWalking OAP server:
+You can also install SkyWalking UI to view the data. To run it on Docker:
- ```shell
- sudo docker run --name skywalking -d -p 1234:1234 -p 12800:12800 --restart always --link elasticsearch:elasticsearch -e SW_STORAGE=elasticsearch -e SW_STORAGE_ES_CLUSTER_NODES=elasticsearch:9200 apache/skywalking-oap-server:8.7.0-es6
- ```
+```shell
+sudo docker run --name skywalking-ui -d -p 8080:8080 --link skywalking:skywalking -e SW_OAP_ADDRESS=skywalking:12800 --restart always apache/skywalking-ui
+```
-2. SkyWalking Web UI:
- 1. Run SkyWalking web UI Server:
+You should be able to access the UI from your browser:
- ```shell
- sudo docker run --name skywalking-ui -d -p 8080:8080 --link skywalking:skywalking -e SW_OAP_ADDRESS=skywalking:12800 --restart always apache/skywalking-ui
- ```
+<!--  -->
- 2. Access the web UI of SkyWalking:
- You can access the dashboard from a browser: http://10.110.149.175:8080 It will show the following
- if the installation is successful.
- 
+Now if you make requests to APISIX:
-3. Test:
+```shell
+curl -v http://10.110.149.192:9080/uid/12
+```
- - Access to upstream services through accessing APISIX:
+```shell
+HTTP/1.1 200 OK
+OK
+...
+```
- ```bash
- $ curl -v http://10.110.149.192:9080/uid/12
- HTTP/1.1 200 OK
- OK
- ...
- ```
+You should be able to see the topology of all services in your SkyWalking UI:
- - Open the web UI of SkyWalking:
+
- ```shell
- http://10.110.149.175:8080/
- ```
+You should also be able to see traces from all services:
- You can see the topology of all services\
- \
- You can also see the traces from all services\
- 
+
## Disable Plugin
-When you want to disable the SkyWalking plugin on a route/service, it is very simple,
- you can delete the corresponding JSON configuration in the plugin configuration,
- no need to restart the service, it will take effect immediately:
+To disable the `skywalking` 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.
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uris": [
@@ -183,50 +219,10 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335
}'
```
-The SkyWalking plugin has been disabled now. The step works in the same fashion for other plugins.
-
-If you want to completely disable the SkyWalking plugin, for example, stopping the background report timer,
-you will need to comment out the plugin in the `config.yaml`:
+To completely disable the `skywalking` Plugin, i.e to stop the background report timer, you need to remove the Plugin from your configuration file (`conf/config.yaml`):
```yaml
plugins:
- - ... # plugin you need
- #- skywalking
-```
-
-And then reload APISIX.
-
-## Upstream services(Code With SpringBoot)
-
-```java
-import org.springframework.web.bind.annotation.PathVariable;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
-import javax.servlet.http.HttpServletRequest;
-
-@RestController
-public class TestController {
- @RequestMapping("/uid/{count}")
- public String getUidList(@PathVariable("count") String countStr, HttpServletRequest request) {
- return "OK";
- }
-}
-```
-
-Configure the SkyWalking agent when starting the service.
-
-Update the file of `agent/config/agent.config`
-
-```shell
-agent.service_name=yourservername
-collector.backend_service=10.110.149.175:11800
-```
-
-Run the script:
-
-```shell
-nohup java -javaagent:/root/skywalking/app/agent/skywalking-agent.jar \
--jar /root/skywalking/app/app.jar \
---server.port=8089 \
-2>&1 > /root/skywalking/app/logs/nohup.log &
+ - ...
+ # - skywalking
```
diff --git a/docs/en/latest/plugins/zipkin.md b/docs/en/latest/plugins/zipkin.md
index 9e9e8188b..f45d96930 100644
--- a/docs/en/latest/plugins/zipkin.md
+++ b/docs/en/latest/plugins/zipkin.md
@@ -1,5 +1,11 @@
---
title: Zipkin
+keywords:
+ - APISIX
+ - Plugin
+ - Zipkin
+ - zipkin
+description: This document contains information about the Apache zipkin Plugin.
---
<!--
@@ -23,21 +29,21 @@ title: Zipkin
## Description
-[Zipkin](https://github.com/openzipkin/zipkin) an open source distributed tracing system. This plugin is supported to collect tracing and report to Zipkin Collector based on [Zipkin API specification](https://zipkin.io/pages/instrumenting.html).
+[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).
-It's 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), which are support Zipkin [v1](https://zipkin.io/zipkin-api/zipkin-api.yaml)/[v2](https://zipkin.io/zipkin-api/zipkin2-api.yaml) format. And of course, it can integrate other tracing systems adapted to Zipkin v1/v2 format as well.
+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.
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-| ------------ | ------ | ----------- | -------- | ------------ | ------------------------------------------------------------------------------- |
-| endpoint | string | required | | | the http endpoint of Ziplin, for example: `http://127.0.0.1:9411/api/v2/spans`. |
-| sample_ratio | number | required | | [0.00001, 1] | the ratio of sample |
-| service_name | string | optional | "APISIX" | | service name for zipkin reporter |
-| server_addr | string | optional | | | IPv4 address for zipkin reporter, default is nginx built-in variables $server_addr, here you can specify your external ip address. |
-| span_version | integer| optional | 2 | [1, 2] | the version of span type |
-
-Currently each traced request will create spans below:
+| 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. |
+a
+Each traced request will create the spans shown below:
```
request
@@ -45,7 +51,7 @@ request
└── response: from the beginning of header filter to the beginning of log
```
-Previously we created spans below:
+For older versions (set `span_version` attribute to `1`), these spans are created:
```
request
@@ -55,13 +61,54 @@ request
└── body_filter
```
-Note: the name of span doesn't represent the corresponding Nginx's phase.
+:::note
+
+The span name doesn't represent the corresponding Nginx phase.
+
+:::
-If you need to be compatible with old style, we can set `span_version` to 1.
+### Sample code for upstream configuration
-## How To Enable
+```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
-Here's an example, enable the zipkin plugin on the specified route:
+ 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
+}
+
+func main(){
+ r := gin.Default()
+
+ tracer := GetTracer(...)
+
+ // 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()
+ })
+
+}
+```
+
+## Enabling the Plugin
+
+The example below enables the Plugin on a specific Route:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -85,40 +132,42 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}'
```
-You also can complete the above operation through the web interface, first add a route, then add zipkin plugin:
-
-
+<!-- You also can complete the above operation through the web interface, first add a route, then add zipkin plugin:
-## Test Plugin
+ -->
-### Run the Zipkin instance
+## Example usage
-e.g. using docker:
+You need to have your Zipkin instance running. You can run Zipkin on Docker by running:
-```
+```shell
docker run -d -p 9411:9411 openzipkin/zipkin
```
-Here is a test example:
+Now, when you make requests, it will be updated in Zipkin:
```shell
curl http://127.0.0.1:9080/index.html
+```
+
+```shell
HTTP/1.1 200 OK
...
```
-Then you can use a browser to access `http://127.0.0.1:9411/zipkin`, the webUI of Zipkin:
+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):
-### Run the Jaeger instance
+### Reporting traces to Jaeger
-Besides Zipkin, this plugin supports reporting the traces to Jaeger as well. Here is a sample run on docker.
-Run Jaeger backend on docker first:
+The Plugin also supports reporting traces to Jaeger. First, you have to have Jaeger running.
-```
+To run it on Docker:
+
+```shell
docker run -d --name jaeger \
-e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
-p 16686:16686 \
@@ -126,7 +175,7 @@ docker run -d --name jaeger \
jaegertracing/all-in-one:1.31
```
-Create a route with Zipkin plugin like Zipkin's example:
+Similar to configuring for Zipkin, create a Route and enable the Plugin:
```
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -150,15 +199,18 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}'
```
-Access the service:
+Now, when you make requests, it will be updated on Jaeger:
```shell
curl http://127.0.0.1:9080/index.html
+```
+
+```shell
HTTP/1.1 200 OK
...
```
-Then you can access `http://127.0.0.1:16686`, the WebUI of Jaeger, to view traceson browser:
+You can access the Jaeger UI to view the traces in endpoint [http://127.0.0.1:16686](http://127.0.0.1:16686):
@@ -166,9 +218,7 @@ Then you can access `http://127.0.0.1:16686`, the WebUI of Jaeger, to view trace
## Disable Plugin
-When you want to disable the zipkin plugin, it is very simple,
- you can delete the corresponding json configuration in the plugin configuration,
- no need to restart the service, it will take effect immediately:
+To disable 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.
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -185,44 +235,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}
}'
```
-
-The zipkin plugin has been disabled now. It works for other plugins.
-
-## example code for upstream ( golang with Gin )
-
-```golang
-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
-
- 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
-}
-
-func main(){
- r := gin.Default()
-
- tracer := GetTracer(...)
-
- // 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()
- })
-
-}
-```