Merge pull request #415 from jodh-intel/support-opentracing

tracing: Add OpenTracing support

.gitignore

@@ -1,4 +1,3 @@
 kata-agent
 kata-agent.service
-agent
 coverage.txt

Gopkg.toml

@@ -8,7 +8,7 @@
 
 [[constraint]]
   name = "github.com/mdlayher/vsock"
-  revision = "738c88d6e4cfd60e8124a5344fa10d205fd828b9"
+  revision = "676f733b747cd6406f297a51bd086ee8ec8abdbe"
 
 [[constraint]]
   name = "github.com/opencontainers/runc"
@@ -46,6 +46,11 @@
   name = "github.com/containerd/console"
   revision = "2748ece16665b45a47f884001d5831ec79703880"
 
+[[constraint]]
+  name = "github.com/uber/jaeger-client-go"
+  version = "2.15.0"
+
+
 [prune]
   non-go = true
   go-tests = true

Makefile

@@ -11,17 +11,53 @@ PREFIX := /usr
 BINDIR := $(PREFIX)/bin
 # Define if agent will be installed as init
 INIT := no
+
+# Set to "yes" if agent should support OpenTracing with http://jaegertracing.io.
+TRACE := no
+
+# Tracing cannot currently be supported when running the agent as PID 1 since
+# the tracing requires additional services to be started _before_ the agent
+# process starts.
+#
+# These services are required since Jaeger does not currently support VSOCK.
+# Once Jaeger does support VSOCK, this limitation can be removed as the
+# additional services will no longer be required.
+#
+# See TRACING.md for further details.
+ifeq ($(TRACE),yes)
+  ifeq ($(INIT),yes)
+    $(error ERROR: "TRACE=yes" requires "INIT=no")
+  endif
+endif
+
+# If "yes", install additional services to redirect guest OS journal messages
+# to the host using VSOCK.
+TRACE_DEV_MODE := no
+
 # Path to systemd unit directory if installed as not init.
 UNIT_DIR := /usr/lib/systemd/system
 
+# Path to systemd drop-in snippet directory used to override the agent's
+# service without having to modify the pristine agent service file.
+SNIPPET_DIR := /etc/systemd/system/$(AGENT_SERVICE).d/
+
 GENERATED_FILES :=
 
 ifeq ($(INIT),no)
-# Unit file to start kata agent in systemd systems
-UNIT_FILES = kata-agent.service
-GENERATED_FILES := $(UNIT_FILES)
-# Target to be reached in systemd services
-UNIT_FILES += kata-containers.target
+    # Unit file to start kata agent in systemd systems
+    UNIT_FILES = kata-agent.service
+    GENERATED_FILES := $(UNIT_FILES)
+    # Target to be reached in systemd services
+    UNIT_FILES += kata-containers.target
+endif
+
+ifeq ($(TRACE),yes)
+    UNIT_FILES += jaeger-client-socat-redirector.service
+endif
+
+ifeq ($(TRACE_DEV_MODE),yes)
+    UNIT_FILES += kata-journald-host-redirect.service
+    SNIPPET_FILES += kata-redirect-agent-output-to-journal.conf
 endif
 
 VERSION_FILE := ./VERSION
@@ -32,9 +68,9 @@ COMMIT := $(if $(shell git status --porcelain --untracked-files=no),${COMMIT_NO}
 VERSION_COMMIT := $(if $(COMMIT),$(VERSION)-$(COMMIT),$(VERSION))
 ARCH := $(shell go env GOARCH)
 ifeq ($(SECCOMP),yes)
-	BUILDTAGS := seccomp
+    BUILDTAGS := seccomp
 else
-	SECCOMP=no
+    SECCOMP=no
 endif
 # go build common flags
 BUILDFLAGS := -buildmode=pie
@@ -56,6 +92,11 @@ ifeq ($(INIT),no)
 	@echo "Installing systemd unit files..."
 	$(foreach f,$(UNIT_FILES),$(call INSTALL_FILE,$f,$(UNIT_DIR)))
 endif
+ifeq ($(TRACE_DEV_MODE),yes)
+	@echo "Installing systemd snippet files..."
+	@mkdir -p $(SNIPPET_DIR)
+	$(foreach f,$(SNIPPET_FILES),$(call INSTALL_FILE,$f,$(SNIPPET_DIR)))
+endif
 
 build-image:
 	# build an docker image for development

README.md

@@ -3,7 +3,27 @@
 
 # Kata Containers Agent
 
-This project implements an agent meant to be run inside a virtual machine.
+* [Debug mode](#debug-mode)
+* [Developer mode](#developer-mode)
+* [Enable trace support](#enable-trace-support)
 
-The goal for this component is to spawn containers and processes inside this
-virtual machine, on behalf of the runtime running on the host.
+This project implements an agent called `kata-agent` that runs inside a virtual machine (VM).
+
+The agent manages container processes inside the VM, on behalf of the
+[runtime](https://github.com/kata-containers/runtime) running on the host.
+
+## Debug mode
+
+To enable agent debug output, add the `agent.log=debug` option to the guest kernel command line.
+
+See the [developer guide](https://github.com/kata-containers/documentation/blob/master/Developer-Guide.md#enable-full-debug) for further details.
+
+## Developer mode
+
+Add `agent.devmode` to the guest kernel command line to allow the agent
+process to coredump (disabled by default). Specifying this option implicitly
+enables [debug mode](#debug-mode).
+
+## Enable trace support
+
+See [the tracing guide](TRACING.md).