JarCastingZIO telemetry
ZIO telemetry is purely-functional and type-safe. It provides clients for OpenTracing and OpenTelemetry
OpenTracing
OpenTracing is a standard and API for distributed tracing, i.e. collecting timings, and logs across process boundaries. Well known implementations are Jaeger and Zipkin.
First, add the following dependency to your build.sbt:
"dev.zio" %% "zio-opentracing" % <version>
To use ZIO telemetry, you will need a Clock and a OpenTelemetry service in your environment:
import io.opentracing.mock.MockTracer
import io.opentracing.propagation._
import zio._
import zio.clock.Clock
import zio.opentracing._
val tracer = new MockTracer
val managedEnvironment =
for {
clock_ <- ZIO.environment[Clock].toManaged_
ot <- managed(tracer)
} yield new Clock with Telemetry {
override val clock: Clock.Service[Any] = clock_.clock
override def telemetry: Telemetry.Service = ot.telemetry
}
After importing import zio.opentracing._, additional combinators on ZIOs are available to support starting child spans, tagging, logging and managing baggage.
// start a new root span and set some baggage item
val zio = UIO.unit
.setBaggage("foo", "bar")
.root("root span")
// start a child of the current span, set a tag and log a message
val zio = UIO.unit
.tag("http.status_code", 200)
.log("doing some serious work here!")
.span("child span")
To propagate contexts across process boundaries, extraction and injection can be used. The current span context is injected into a carrier, which is passed through some side channel to the next process. There it is injected back and a child span of it is started. For the example we use the standardized TextMap carrier. For details about extraction and injection, please refer to OpenTracing Documentation.
Due to the use of the (mutable) OpenTracing carrier APIs, injection and extraction are not referentially transparent.
val buffer = new TextMapAdapter(mutable.Map.empty.asJava)
for {
_ <- zio.inject(Format.Builtin.TEXT_MAP, buffer)
_ <- zio.spanFrom(Format.Builtin.TEXT_MAP, buffer, "child of remote span")
} yield buffer
Example usage
Firstly, start Jaeger by running 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
To check if it's running properly visit Jaeger UI. More info can be found here.
Our application contains two services:
Proxy service
Represents entry point to example distributed system. It exposes /statuses endpoint which returns list of system's services statuses.
In order to start service run:
sbt "opentracingExample/runMain zio.telemetry.opentracing.example.ProxyServer"
If it's start properly it should be available on http://0.0.0.0:8080/statuses.
Backend service
Represents "internal" service of the system. It exposes /status endpoint which returns service status.
In order to start service run:
sbt "opentracingExample/runMain zio.telemetry.opentracing.example.BackendServer"
If it's start properly it should be available on http://0.0.0.0:9000/status.
Configuration is given in application.conf.
After both services are properly started, running following command
curl -X GET http://0.0.0.0:8080/statuses
should return following response:
{
"data": [
{
"name": "backend",
"version": "1.0.0",
"status": "up"
},
{
"name": "proxy",
"version": "1.0.0",
"status": "up"
}
]
}
Simultaneously, it will create trace that will be stored in Jaeger backend.
OpenTelemetry
Use this dependency instead:
"dev.zio" %% "zio-opentelemetry" % <version>
First, start Jaeger by running
docker run --rm -it \
-p 16686:16686 \
-p 14250:14250 \
jaegertracing/all-in-one:1.16
Then start the proxy server
sbt "opentelemetryExample/runMain zio.telemetry.opentelemetry.example.ProxyServer"
and the backend server
sbt "opentelemetryExample/runMain zio.telemetry.opentelemetry.example.BackendServer"
Now perform the following request:
curl -X GET http://0.0.0.0:8080/statuses
and head over to http://localhost:16686/ to see the result.
