Phobos.Tracing.Jaeger

Jaeger is one of the most popular open source distributed engines and it is fully supported by Phobos.

To access Phobos' installation, you need to install the Phobos.Tracing.Jaeger 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.Jaeger can be configured via HOCON, as is the case with all first party drivers supported by Phobos:

###############################################
# Phobos.Tracing.Jaeger Reference Config File #
###############################################

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

	# Based on the settings defined in https://github.com/jaegertracing/jaeger-client-csharp#configuration-via-environment
	jaeger{		
		# When set to "on" all of these settings will be auto-populated from the environment variables
		# supported by the Jaeger driver, instead of reading in HOCON settings. 
		# Learn more about those variables at the link above.
		load-from-env = off

		# When using the Jaeger UDP transport, fill in these settings
		agent{
			# The IP address or hostname of the Jaeger UDP endpoint
			host = ""

			# The port used for transmitting Jaeger spans to the Jaeger agent.
			# Defaults to 6831, the port used for accepting jaeger.thrift messages
			# via the compact thrift protocol. See more at https://www.jaegertracing.io/docs/getting-started/
			port = 6831
		}

		# If populated, will override the settings specified `jaeger.agent` HOCON
		# and will use Jaeger's HTTP transport instead via an endpoint such as
		# http://localhost:14268/api/traces
		endpoint = ""

		# Jaeger authentication options
		auth{
			# The auth token to send as "Bearer" to the endpoint.
			# To be used instead of `auth.user` and `auth.password`.
			token = ""

			# The username to use for basic authentication to the HTTP endpoint.
			user = ""

			# The password to use for authenticating with Jaeger HTTP endpoint
			password = ""
		}

		# Comma separated list of formats to use for propagating the trace context. 
		# Defaults to the standard Jaeger format. Valid values are jaeger and b3
		propagation = [jaeger, b3]

		# Settings for the reporter
		reporter{
			# When set to "on," will cause all outbound spans to be logged first
			log-spans = off

			# The maximum number of outbound spans to queue at any given time
			max-queue-size = 2000

			# The interval at which spans will be flushed to the Jaeger agent
			flush-interval = 100ms
		}

		# A comma separated list of name = value tags that
		# will be appended automatically to each outgoing span.
		tags {
			"source" = "phobos.tracing"
		}

		# When set to `on`, will cause Jaeger to record spans using 128bit IDs instead of 64bit.
		use-128bit-id = on
	}
}

Jaeger UDP Reporting

Jaeger supports two different modes of reporting ISpan instances back to the Jaeger query and analysis dashboard:

In large-scale environments we recommend that developers use agent-based reporting as it is ultimately lower-latency and more scalable since it distributes work-loads and pre-aggregation across a larger portion of the network. It is more complex to organize deployments under this configuration initially, but once you've figured out how to do it once it's easy to repeat afterwards. Higher upfront cost; more sustainable operation costs over time.

To run Phobos.Tracing.Jaeger with UDP reporting enabled, you should use a HOCON configuration that looks like this:

phobos{
    tracing{
        provider-type = jaeger
        jaeger{
            agent{ # for UDP reporting
                host = localhost
                port = 6831
            }
        }
    }
}

Jaeger HTTP Reporting

For local testing, development, and lower throughput applicatiojns it can be much easier to report ISpan instances directly back to the Jaeger collector over HTTP since the setup overhead is significantly reduced.

If that's the case for your environment, you can configure Phobos.Tracing.Jaeger to report over HTTP instead:

phobos{
    tracing{
        provider-type = jaeger
        jaeger{
            # HTTP reporting to collector
            endpoint = "http://localhost:14268/api/traces"
        }
    }
}

Configuration via Environment Variables

Phobos.Tracing.Jaeger is implemented on top of the official Jaeger driver for .NET and C#, which supports the ability to fully configure the Jaeger cliently solely through environment variables.

To configure Phobos.Tracing.Jaeger this way, use the following HOCON syntax to allow the driver to perform its work via environment variables instead:

phobos{
    tracing{
        provider-type = jaeger
        jaeger.load-from-env = on
    }
}

You can see the full list of environment variable configuration options supported by Jaeger here.

Test-Driving Jaeger

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

Fire up the Jaeger "all-in-one" Docker image via the following command:

docker run -d --name jaeger -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 -p 5775:5775/udp -p 6831:6831/udp -p 6832:6832/udp -p 5778:5778 -p 16686:16686 -p 14268:14268 -p 9411:9411 jaegertracing/all-in-one:1.6

This will spin up a Jaeger agent, collector, and dashboard all inside the same Docker container. It's perfect for local development and testing.

Next, Clone our phobos-samples repository and run any of the samples in there with the Jaeger driver installed and properly configured via HOCON.

All-in-One Endpoints

The all-in-one Jaeger Docker image opens up several network endpoints. Here are the useful ones as far as your purposes are concerned:

  1. 6831 - UDP collector port for agents.
  2. 16686 - HTTP port for viewing the Jaeger dashboard and query engine.
  3. 14268 - HTTP port for reporting spans directly to the Jaeger collector.