From c734cc3e64fe4d342f28e16f0bf80531161bb426 Mon Sep 17 00:00:00 2001 From: Andrii Kushch Date: Wed, 9 Mar 2022 18:42:06 +0100 Subject: [PATCH] caddyfile: tracing directive (#205) * Add documentation for tracing directive * Update header in tracing.md Co-authored-by: Matt Holt * Update documentation in tracing.md Co-authored-by: Matt Holt * add link to the repository * add link to gRPC repo and w3c specification Co-authored-by: Andrii Kushch <> Co-authored-by: Matt Holt --- src/docs/markdown/caddyfile/directives.md | 3 ++ .../markdown/caddyfile/directives/tracing.md | 53 +++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 src/docs/markdown/caddyfile/directives/tracing.md diff --git a/src/docs/markdown/caddyfile/directives.md b/src/docs/markdown/caddyfile/directives.md index ed80068..d32d97d 100644 --- a/src/docs/markdown/caddyfile/directives.md +++ b/src/docs/markdown/caddyfile/directives.md @@ -62,6 +62,7 @@ Directive | Description **[route](/docs/caddyfile/directives/route)** | A group of directives treated literally as single unit **[templates](/docs/caddyfile/directives/templates)** | Execute templates on the response **[tls](/docs/caddyfile/directives/tls)** | Customize TLS settings +**[tracing](/docs/caddyfile/directives/tracing)** | Integration with OpenTelemetry tracing **[try_files](/docs/caddyfile/directives/try_files)** | Rewrite that depends on file existence **[uri](/docs/caddyfile/directives/uri)** | Manipulate the URI @@ -104,6 +105,8 @@ Because matcher tokens all work the same, the various possibilities for the matc Many directives manipulate the HTTP handler chain. The order in which those directives are evaluated matters, so a default ordering is hard-coded into Caddy: ```caddy-d +tracing + map root diff --git a/src/docs/markdown/caddyfile/directives/tracing.md b/src/docs/markdown/caddyfile/directives/tracing.md new file mode 100644 index 0000000..e74cd7e --- /dev/null +++ b/src/docs/markdown/caddyfile/directives/tracing.md @@ -0,0 +1,53 @@ +--- +title: tracing (Caddyfile directive) +--- + +# tracing + +It provides integration with OpenTelemetry tracing facilities. + +When enabled, it will propagate an existing trace context or initialize a new one. + +It is based on [github.com/open-telemetry/opentelemetry-go](https://github.com/open-telemetry/opentelemetry-go). + +It uses [gRPC](https://github.com/grpc/) as an exporter protocol and W3C [tracecontext](https://www.w3.org/TR/trace-context/) and [baggage](https://www.w3.org/TR/baggage/) as propagators. + +## Syntax + +```caddy-d +tracing { + [span ] +} +``` + +- **<span_name>** - is a span name. Please see span naming [guidelines](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.7.0/specification/trace/api.md). + +## Configuration + +### Environment variables + +It can be configured using the environment variables defined +by the [OpenTelemetry Environment Variable Specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md). + +For the exporter configuration details, please +see [spec](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.7.0/specification/protocol/exporter.md). + +For example: + +```bash +export OTEL_EXPORTER_OTLP_HEADERS="myAuthHeader=myToken,anotherHeader=value" +export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://my-otlp-endpoint:55680 +``` + +## Examples + +Here is a **Caddyfile** example: + +``` +handle /myHandler { + tracing { + span my-span + } + reverse_proxy 127.0.0.1:8081 +} +```