From 58fcce0bc45a5157a5fcf9d04bc8f87429450d99 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Mon, 18 Mar 2019 15:38:24 +0000 Subject: [PATCH 1/2] docs: Simplify trace terminology Simplify agent tracing terminology by renaming "trace type" to "trace mode". This allows what was called "trace sub-type" to be called "trace type". Fixes #488. Signed-off-by: James O. D. Hunt --- TRACING.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/TRACING.md b/TRACING.md index f49666d183..07b1643ceb 100644 --- a/TRACING.md +++ b/TRACING.md @@ -4,9 +4,9 @@ * [OpenTracing summary](#opentracing-summary) * [Jaeger tracing architecture](#jaeger-tracing-architecture) * [Guest to Host communication using VSOCK](#guest-to-host-communication-using-vsock) -* [Types of Agent tracing](#types-of-agent-tracing) - * [Primary trace types](#primary-trace-types) - * [Tracing sub-types](#tracing-sub-types) +* [Agent tracing terminology](#agent-tracing-terminology) + * [Trace modes](#trace-modes) + * [Trace types](#trace-types) * [Enabling tracing](#enabling-tracing) * [Enabling dynamic tracing](#enabling-dynamic-tracing) * [Enabling static tracing](#enabling-static-tracing) @@ -96,20 +96,22 @@ Further details: For tracing to work, the host system must have a Jaeger agent running. -# Types of Agent tracing +# Agent tracing terminology -## Primary trace types +## Trace modes -Two types of agent tracing are available: +The agent supports two different tracing modes: -| Trace type | Description | Use-case | VM shutdown controller | Limitations | +| Trace mode | Description | Use-case | VM shutdown controller | Limitations | |-|-|-|-|-| | Static | Traces from agent start to agent shutdown. | Obtain holistic view of agent activities. | Agent | None | -| Dynamic | Traces begin when the gRPC `StartTracing()` API is called and end when the corresponding `StopTracing()` API is called. | on-demand (partial) tracing. | Runtime | Only "isolated" sub-type supported. | +| Dynamic | Traces begin when the gRPC `StartTracing()` API is called and end when the corresponding `StopTracing()` API is called. | on-demand (partial) tracing. | Runtime | Only "isolated" type supported. | -## Tracing sub-types +## Trace types -| Trace sub-type | Description | Use-case | Notes | +Each trace mode is sub-divided into two different types: + +| Trace type | Description | Use-case | Notes | |-|-|-|-| | isolated | The traces only apply to the agent; after the container has been destroyed, the first span will start at agent startup and the last at agent shutdown | Observing agent lifespan. | | | collated | In this mode, spans are associated with their `kata-runtime` initiated counterparts. | Understanding how the runtime calls the agent. | Requires runtime tracing to be enabled in `configuration.toml` (`enable_tracing=true`). | @@ -120,7 +122,7 @@ Two types of agent tracing are available: Call the gRPC `StartTracing()` API to start tracing and the corresponding `StopTracing()` API to stop tracing. -> **Note:** Dynamic tracing will always use an isolated sub-type. +> **Note:** The dynamic tracing mode will always use an isolated type. ## Enabling static tracing From f64fe3cef8d7d4f884c8593579f887d1415b5162 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Mon, 18 Mar 2019 15:39:12 +0000 Subject: [PATCH 2/2] docs: Don't mention runtime guest kernel CLI for agent tracing Remove the example showing how to set the trace mode in the runtime's configuration file. The reason for doing this being that the plan is for the runtime to control adding such guest kernel command line options as part of https://github.com/kata-containers/runtime/issues/1369. Signed-off-by: James O. D. Hunt --- TRACING.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/TRACING.md b/TRACING.md index 07b1643ceb..9b6ee41594 100644 --- a/TRACING.md +++ b/TRACING.md @@ -127,7 +127,7 @@ Call the gRPC `StartTracing()` API to start tracing and the corresponding `StopT ## Enabling static tracing Static tracing is enabled by adding the `agent.trace` option in the -`kernel_params=` variable in the runtime's `configuration.toml` file. +guest kernels command line. ### Static tracing options @@ -139,13 +139,6 @@ following: | "isolated" | `agent.trace=isolated` (or just `agent.trace`) | | "collated" | `agent.trace=collated` | -For example, to enable isolated tracing explicitly, add the following to the -runtime's `configuration.toml` file: - -``` -kernel_params = "agent.trace=isolated ... " -``` - > **Note:** > > Agent tracing is separate from the tracing for other Kata Containers