From daa8487670a18aec0cda1b6fa756626d306b97da Mon Sep 17 00:00:00 2001 From: Brian Goff Date: Thu, 4 Oct 2018 10:08:07 -0700 Subject: [PATCH 1/2] Add docs for tracing --- DEBUGGING.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 DEBUGGING.md diff --git a/DEBUGGING.md b/DEBUGGING.md new file mode 100644 index 000000000..25c8f349d --- /dev/null +++ b/DEBUGGING.md @@ -0,0 +1,35 @@ +Debugging virtual-kubelet +========================= + +## Metrics + +Not implemented. + +## Tracing + +virtual-kubelet uses [OpenCensus](https://www.opencensus.io) to record traces. These traces include requests on the HTTP API as well as the reconciliation loop which reconciles virtual-kubelet pods with what's in the Kubernetes API server. + +The granularity of traces may depend on the provider being used. + +### Tracing Exporters + +Traces are collected and then exportered to any configured exporter. Built-in exporters currently include: + +- `jaeger` - [Jaeger Tracing](https://www.jaegertracing.io), supports configuration through environment variables. + - `JAEGER_ENDPOINT` - Jaeger HTTP Thrift endpoint, e.g. `http://localhost:14268` + - `JAGER_AGENT_ENDPOINT` - Jaeger agent address, e.g. `localhost:6831` + - `JAEGER_USER` + - `JAEGER_PASSWORD` +- `zpages` - [OpenCensus Zpages](https://opencensus.io/core-concepts/z-pages/). Currently supports configuration through environment variables, but this interface is **not** considered stable. + - ZPAGES_PORT - e.g. `localhost:8080` sets the address to setup the HTTP server to serve zpages on. Will be available at `http://
:/debug/tracez` + +If consuming virtual-kubelet as a library you can configure your own tracing exporter. + +Traces propagated from other services must be propagated using Zipkin's B3 format. Other formats may be supported in the future. + +### Tracing Configuration + +- `--trace-exporter` - Sets the exporter to use. Multiple exporters can be specified. If this is unset, traces are not exported. +- `--trace-service-name` - Sets the name of the service, defaults to `virtual-kubelet` but can be anything. This value is passee to the exporter purely for display purposes. +- `--trace-tag` - Adds tags in a `=` form which is included with collected traces. Think of this like log tags but for traces. +- `--trace-sample-rate` - Sets the probability for traces to be recorded. Traces are considered an expensive operation so you may want to set this to a lower value. Range is a value of 0 to 100 where 0 is never trace and 100 is always trace. \ No newline at end of file From ae49bbfd1146dfd98861d3417ad88cf8fe4cd94c Mon Sep 17 00:00:00 2001 From: Brian Goff Date: Thu, 4 Oct 2018 10:09:11 -0700 Subject: [PATCH 2/2] Fix filename typo s/cencus/census/ --- DEBUGGING.md | 6 +++--- cmd/{cencus_jaeger.go => census_jaeger.go} | 0 cmd/{cencus_test.go => census_test.go} | 0 3 files changed, 3 insertions(+), 3 deletions(-) rename cmd/{cencus_jaeger.go => census_jaeger.go} (100%) rename cmd/{cencus_test.go => census_test.go} (100%) diff --git a/DEBUGGING.md b/DEBUGGING.md index 25c8f349d..457ed39bd 100644 --- a/DEBUGGING.md +++ b/DEBUGGING.md @@ -9,11 +9,11 @@ Not implemented. virtual-kubelet uses [OpenCensus](https://www.opencensus.io) to record traces. These traces include requests on the HTTP API as well as the reconciliation loop which reconciles virtual-kubelet pods with what's in the Kubernetes API server. -The granularity of traces may depend on the provider being used. +The granularity of traces may depend on the service provider (e.g. `azure`, `aws`, etc) being used. ### Tracing Exporters -Traces are collected and then exportered to any configured exporter. Built-in exporters currently include: +Traces are collected and then exported to any configured exporter. Built-in exporters currently include: - `jaeger` - [Jaeger Tracing](https://www.jaegertracing.io), supports configuration through environment variables. - `JAEGER_ENDPOINT` - Jaeger HTTP Thrift endpoint, e.g. `http://localhost:14268` @@ -30,6 +30,6 @@ Traces propagated from other services must be propagated using Zipkin's B3 forma ### Tracing Configuration - `--trace-exporter` - Sets the exporter to use. Multiple exporters can be specified. If this is unset, traces are not exported. -- `--trace-service-name` - Sets the name of the service, defaults to `virtual-kubelet` but can be anything. This value is passee to the exporter purely for display purposes. +- `--trace-service-name` - Sets the name of the service, defaults to `virtual-kubelet` but can be anything. This value is passed to the exporter purely for display purposes. - `--trace-tag` - Adds tags in a `=` form which is included with collected traces. Think of this like log tags but for traces. - `--trace-sample-rate` - Sets the probability for traces to be recorded. Traces are considered an expensive operation so you may want to set this to a lower value. Range is a value of 0 to 100 where 0 is never trace and 100 is always trace. \ No newline at end of file diff --git a/cmd/cencus_jaeger.go b/cmd/census_jaeger.go similarity index 100% rename from cmd/cencus_jaeger.go rename to cmd/census_jaeger.go diff --git a/cmd/cencus_test.go b/cmd/census_test.go similarity index 100% rename from cmd/cencus_test.go rename to cmd/census_test.go