`Phobos.Tracing.Zipkin`

Petabridge offers first-party support for a number of popular distributed tracing backends, Zipkin being one of them. Phobos' Zipkin integration is available only when you install the Phobos.Tracing.Zipkin NuGet package from your organization's Phobos NuGet feed.

NOTE

In order to use any of the Phobos integrations, you will need to first configure your akka.actor.provider setting to use one of the ActorRefProvider implementations provided by the Phobos.Actor.* NuGet packages. Click here for details.

Configuring via HOCON

Phobos.Tracing.Zipkin can be configured via HOCON, as is the case with all first party drivers supported by Phobos:

##################################
# Phobos.Tracing.Zipkin Reference Config File #
##################################

phobos.tracing{
	# Will cause the Zipkin driver to be loaded.	
	provider-type = zipkin

	zipkin{		

		# Valid values include CLIENT, SERVER, PRODUCER, CONSUMER
		# When this setting is provided, Petabridge.Tracing.Zipkin will default
		# to initializing all spans with the provided type.
		default-spankind = ""

		# When set to "on", this will cause all Spans recorded by the driver to be flagged
		# as "debug" spans - that information can be used inside the Zipkin UI.
		debug-enabled = off


		# If you wish to use the Zipkin HTTP transport, fill in the `http.uri` setting
		http{
			# The full URI of the Zipkin HTTP endpoint we'll be writing to,
			# i.e. http://localhost:9411. Must be set in order for the driver to work.
			uri = ""

			# The maximum number of Spans to include in a single batch. The larger this value,
			# the longer each HTTP operation to Zipkin will take to some degree.
			batch-size = 30

			# The Petabridge.Tracing.Zipkin driver will wait for either `batch-size` messages or for
			# the batch-interval to be reached before it flushes data to Zipkin. Whichever happens first.
			batch-interval = 100ms

			# The amount of time we will wait before timing out a single HTTP operation to Zipkin.
			# Petabridge.Tracing.Zipkin can have multiple HTTP operations all running concurrently.
			timeout-interval = 5s
		}

		# If you wish to use the Kafka Zipkin transport INSTEAD of the HTTP transport,
		# fill in the kafka.bootstrap-servers setting with at least one value.
		kafka{
			# A comma delimited list of ip:port combinations for the Kafka bootstrap servers.
			# i.e. "localhost:19092", "localhost:19093"
			bootstrap-servers = []

			# The default topic name to which all Zipkin spans shall be posted.
			# The Zipkin collector is programmed by default to listen on the "zipkin" topic,
			# so unless your Zipkin collector is configured differently you should
			# leave this as-is.
			topic-name = "zipkin"

			# The maximum number of Spans to include in a single batch. The larger this value,
			# the longer each Kafka operation to Zipkin will take to some degree.
			batch-size = 30

			# The Petabridge.Tracing.Zipkin driver will wait for either `batch-size` messages or for
			# the batch-interval to be reached before it flushes data to Kafka. Whichever happens first.
			batch-interval = 100ms

			logging{
				# Allows for logging errors during Kafka Span reporting.
				error = on

				# Verbose debug logging for Kafka Span reporting.
				debug = off
			}
		}
	}
}

The HOCON comments do a reasonable job explaining what all of the settings do and most don't need to be changed. For most production environments your HOCON configuration for work with Zipkin will look like this:

phobos{
    tracing{
        provider-type = zipkin
        zipkin.http.uri = "http://localhost:9411"
    }
}

Aside from configuring the phobos.tracing.provider-type to zipkin the only mandatory setting is the zipkin.http.uri, which tells the underlying Zipkin driver where to send all of the collected traces.

Under the covers, Phobos.Tracing.Zipkin depends on the Petabridge.Tracing.Zipkin driver, which is open source and maintained by Petabridge. At present our driver only supports an HTTP transport, but in the future we may offer gRPC, Azure Event Hubs, and Kafka transports. Please click on the link above and leave a comment on one of our open issues if this is something your organization would find helpful.

Configuring via C#

If you need to be able to customize your Phobos.Tracing.Zipkin driver beyond what the built-in HOCON configuration allows you to do (for instance, changing the OpenTracing.IScopeManger to something other than the default) you can use Phobos' OpenTracing integration to load a Petabridge.Tracing.Zipkin.ZipkinTracer procedurally:

var tracer = new ZipkinTracer(new ZipkinTracerOptions(url, "PhobosApp", debug: true));
OpenTracing.Util.GlobalTracer.Register(tracer);

// instantiates Phobos.Tracing for this ActorSystem if 
// not already started
var actorTracing = Phobos.Tracing.ActorTracing.For(Sys);

Test-Driving Zipkin

If you want to evaluate Phobos in combination with Zipkin, we recommend the following:

Create a local Zipkin instance using docker-compose and the Zipkin + MySQL docker-compose file in our phobos-infrastructure repository.
Clone our phobos-samples repository and run any of the samples in there with the Zipkin driver installed and properly configured via HOCON.