docs: zikpin tracer

.github/workflows/docs.yaml

@@ -40,7 +40,6 @@ jobs:
 
     - name: Check links
       run: make docs docs-check-links
-      continue-on-error: true
 
   docs-build:
     runs-on: ubuntu-latest

site/assets/scss/_variables_project.scss

@@ -7,3 +7,8 @@ Add styles or override variables from the theme here.
 $primary: #280C53;
 $secondary: #802A78;
 $dark: #280C53;
+
+// better style when pre inside tab pane
+.td-content .highlight pre{
+  margin-bottom: 1rem !important;
+}

site/content/en/boilerplates/o11y_prerequisites.md → site/content/en/latest/boilerplates/o11y_prerequisites.md

@@ -1,6 +1,7 @@
 ---
 ---
-Follow the steps from the [Quickstart](../quickstart) to install Envoy Gateway and the example manifest.
+
+Follow the steps from the [Quickstart](../tasks/quickstart) to install Envoy Gateway and the example manifest.
 Before proceeding, you should be able to query the example backend using HTTP.
 
 Envoy Gateway provides an add-ons Helm Chart, which includes all the needing components for observability.

site/content/en/latest/tasks/observability/gateway-exported-metrics.md

@@ -7,7 +7,7 @@ The Envoy Gateway provides a collection of self-monitoring metrics in [Prometheu
 These metrics allow monitoring of the behavior of Envoy Gateway itself (as distinct from that of the EnvoyProxy it managed).
 
 {{% alert title="EnvoyProxy Metrics" color="warning" %}}
-For EnvoyProxy Metrics, please refer to the [EnvoyProxy Observability](./proxy-observability#metrics) to learn more.
+For EnvoyProxy Metrics, please refer to the [EnvoyProxy Metrics](./proxy-metric) to learn more.
 {{% /alert %}}
 
 ## Watching Components

site/content/en/latest/tasks/observability/grafana-integration.md

@@ -9,7 +9,7 @@ This task shows you how to visualise the metrics exposed to Prometheus using Gra
 
 {{< boilerplate o11y_prerequisites >}}
 
-Follow the steps from the [Gateway Observability](../gateway-observability) and [Proxy Observability](../proxy-observability#metrics) to enable Prometheus metrics
+Follow the steps from the [Gateway Observability](./gateway-observability) and [Proxy Metrics](./proxy-metric) to enable Prometheus metrics
 for both Envoy Gateway (Control Plane) and Envoy Proxy (Data Plane).
 
 Expose endpoints:

site/content/en/latest/tasks/observability/proxy-observability.md → site/content/en/latest/tasks/observability/proxy-metric.md

@@ -1,20 +1,14 @@
 ---
-title: "Proxy Observability"
+title: "Proxy Metrics"
 ---
 
 Envoy Gateway provides observability for the ControlPlane and the underlying EnvoyProxy instances.
-This task show you how to config proxy observability, includes metrics, and traces.
+This task show you how to config proxy metrics.
 
 ## Prerequisites
 
 {{< boilerplate o11y_prerequisites >}}
 
-Expose endpoints:
-
-```shell
-TEMPO_IP=$(kubectl get svc tempo -n monitoring -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
-```
-
 ## Metrics
 
 By default, Envoy Gateway expose metrics with prometheus endpoint. 
@@ -51,24 +45,3 @@ kubectl port-forward pod/$OTEL_POD_NAME -n monitoring 19001:19001
 # check metrics 
 curl localhost:19001/metrics  | grep "default/backend/rule/0"
 ```
-
-## Traces
-
-By default, Envoy Gateway doesn't send traces to OpenTelemetry Sink.
-You can enable traces by setting the `telemetry.tracing` in the `EnvoyProxy` CRD.
-
-***Note:*** Envoy Gateway use 100% sample rate, which means all requests will be traced. This may cause performance issues.
-
-```shell
-kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/tracing/default.yaml
-```
-
-Verify traces from tempo:
-
-```shell
-curl -s "http://$TEMPO_IP:3100/api/search" --data-urlencode "q={ component=envoy }" | jq .traces
-```
-
-```shell
-curl -s "http://$TEMPO_IP:3100/api/traces/<trace_id>" | jq
-```

site/content/en/latest/tasks/observability/proxy-trace.md

@@ -0,0 +1,233 @@
+---
+title: "Proxy Tracing"
+---
+
+Envoy Gateway provides observability for the ControlPlane and the underlying EnvoyProxy instances.
+This task show you how to config proxy tracing.
+
+## Prerequisites
+
+{{< boilerplate o11y_prerequisites >}}
+
+Expose Tempo endpoints:
+
+```shell
+TEMPO_IP=$(kubectl get svc tempo -n monitoring -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
+```
+
+## Traces
+
+By default, Envoy Gateway doesn't send traces to any sink.
+You can enable traces by setting the `telemetry.tracing` in the [EnvoyProxy][envoy-proxy-crd] CRD.
+Currently, Envoy Gateway support OpenTelemetry and [Zipkin](../../api/extension_types#zipkintracingprovider) tracer.
+
+### Tracing Provider
+
+The following configurations show how to apply proxy with different providers:
+
+{{< tabpane text=true >}}
+{{% tab header="OpenTelemetry" %}}
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: gateway.networking.k8s.io/v1
+kind: GatewayClass
+metadata:
+  name: eg
+spec:
+  controllerName: gateway.envoyproxy.io/gatewayclass-controller
+  parametersRef:
+    group: gateway.envoyproxy.io
+    kind: EnvoyProxy
+    name: otel
+    namespace: envoy-gateway-system
+---
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: EnvoyProxy
+metadata:
+  name: otel
+  namespace: envoy-gateway-system
+spec:
+  telemetry:
+    tracing:
+      # sample 100% of requests
+      samplingRate: 100
+      provider:
+        backendRefs:
+        - name: otel-collector
+          namespace: monitoring
+          port: 4317
+        type: OpenTelemetry
+      customTags:
+        # This is an example of using a literal as a tag value
+        provider:
+          type: Literal
+          literal:
+            value: "otel"
+        "k8s.pod.name":
+          type: Environment
+          environment:
+            name: ENVOY_POD_NAME
+            defaultValue: "-"
+        "k8s.namespace.name":
+          type: Environment
+          environment:
+            name: ENVOY_GATEWAY_NAMESPACE
+            defaultValue: "envoy-gateway-system"
+        # This is an example of using a header value as a tag value
+        header1:
+          type: RequestHeader
+          requestHeader:
+            name: X-Header-1
+            defaultValue: "-"
+EOF
+```
+
+Verify OpenTelemetry traces from tempo:
+
+```shell
+curl -s "http://$TEMPO_IP:3100/api/search?tags=component%3Dproxy+provider%3Dotel" | jq .traces
+```
+
+{{% /tab %}}
+{{% tab header="Zipkin" %}}
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: gateway.networking.k8s.io/v1
+kind: GatewayClass
+metadata:
+  name: eg
+spec:
+  controllerName: gateway.envoyproxy.io/gatewayclass-controller
+  parametersRef:
+    group: gateway.envoyproxy.io
+    kind: EnvoyProxy
+    name: zipkin
+    namespace: envoy-gateway-system
+---
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: EnvoyProxy
+metadata:
+  name: zipkin
+  namespace: envoy-gateway-system
+spec:
+  telemetry:
+    tracing:
+      # sample 100% of requests
+      samplingRate: 100
+      provider:
+        backendRefs:
+        - name: otel-collector
+          namespace: monitoring
+          port: 9411
+        type: Zipkin
+        zipkin:
+          enable128BitTraceId: true
+      customTags:
+        # This is an example of using a literal as a tag value
+        provider:
+          type: Literal
+          literal:
+            value: "zipkin"
+        "k8s.pod.name":
+          type: Environment
+          environment:
+            name: ENVOY_POD_NAME
+            defaultValue: "-"
+        "k8s.namespace.name":
+          type: Environment
+          environment:
+            name: ENVOY_GATEWAY_NAMESPACE
+            defaultValue: "envoy-gateway-system"
+        # This is an example of using a header value as a tag value
+        header1:
+          type: RequestHeader
+          requestHeader:
+            name: X-Header-1
+            defaultValue: "-"
+EOF
+```
+
+Verify zipkin traces from tempo:
+
+```shell
+curl -s "http://$TEMPO_IP:3100/api/search?tags=component%3Dproxy+provider%3Dzipkin" | jq .traces
+```
+
+{{% /tab %}}
+{{< /tabpane >}}
+
+Query trace by trace id:
+
+```shell
+curl -s "http://$TEMPO_IP:3100/api/traces/<trace_id>" | jq
+```
+
+
+### Sampling Rate
+
+Envoy Gateway use 100% sample rate, which means all requests will be traced.
+This may cause performance issues when traffic is very high, you can adjust
+the sample rate by setting the `telemetry.tracing.samplingRate` in the [EnvoyProxy][envoy-proxy-crd] CRD.
+
+The following configurations show how to apply proxy with 1% sample rates:
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: gateway.networking.k8s.io/v1
+kind: GatewayClass
+metadata:
+  name: eg
+spec:
+  controllerName: gateway.envoyproxy.io/gatewayclass-controller
+  parametersRef:
+    group: gateway.envoyproxy.io
+    kind: EnvoyProxy
+    name: otel
+    namespace: envoy-gateway-system
+---
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: EnvoyProxy
+metadata:
+  name: otel
+  namespace: envoy-gateway-system
+spec:
+  telemetry:
+    tracing:
+      # sample 1% of requests
+      samplingRate: 1
+      provider:
+        backendRefs:
+        - name: otel-collector
+          namespace: monitoring
+          port: 4317
+        type: OpenTelemetry
+      customTags:
+        # This is an example of using a literal as a tag value
+        provider:
+          type: Literal
+          literal:
+            value: "otel"
+        "k8s.pod.name":
+          type: Environment
+          environment:
+            name: ENVOY_POD_NAME
+            defaultValue: "-"
+        "k8s.namespace.name":
+          type: Environment
+          environment:
+            name: ENVOY_GATEWAY_NAMESPACE
+            defaultValue: "envoy-gateway-system"
+        # This is an example of using a header value as a tag value
+        header1:
+          type: RequestHeader
+          requestHeader:
+            name: X-Header-1
+            defaultValue: "-"
+EOF
+```
+
+
+
+[envoy-proxy-crd]: ../../api/extension_types#envoyproxy

site/layouts/shortcodes/boilerplate.html

@@ -1,9 +1,15 @@
-{{- /* This will try to find a resource in the "boilerplates"  top-level content directory */ -}}
 {{- $name := .Get 0 -}}
 {{- $position := .Position }}
+{{- $boilerplates_path := "/boilerplates" -}}
+
+{{- /* check if the page is under versioned path */ -}}
+{{- $url_prefix := (index (split $.Page.File.Dir "/") 0) -}}
+{{- if or (eq $url_prefix "latest") (strings.HasPrefix $url_prefix "v1.") -}}
+    {{- $boilerplates_path = printf "/%s/boilerplates" $url_prefix -}}
+{{- end -}}
 
 {{- if $name -}}
-    {{- $bundle := .Page.GetPage "/boilerplates" -}}
+    {{- $bundle := .Page.GetPage $boilerplates_path -}}
     {{- with $bundle -}}
         {{- $name := printf "%s.md" $name -}}
         {{- $pattern := printf "%s*" $name -}}
@@ -14,7 +20,7 @@
             {{- errorf "Could not find boilerplate '%s' (%s)" $name $position -}}
         {{- end -}}
     {{- else -}}
-        {{- errorf "'boilerplates' directory was not found (%s)" $position -}}
+        {{- errorf "%s directory was not found (%s)" $boilerplates_path $position -}}
     {{- end -}}
 {{- else -}}
     {{- errorf "Missing name in boilerplate (%s)" $position -}}