Kamon http4s
Getting Started
The kamon-http4s
module brings traces and metrics to your http4s based applications.
Kamon kamon-http4s is currently available for Scala 2.12 and 2.13.
Supported releases and dependencies are shown below.
kamon-http4s | status | jdk | scala | http4s |
---|---|---|---|---|
1.0.8-1.0.10 | stable | 8+ | 2.11, 2.12 | 0.18.x |
1.0.13 | stable | 8+ | 2.11, 2.12 | 0.20.x |
2.0.0 | stable | 8+ | 2.11, 2.12 | 0.20.x |
2.0.1 | stable | 8+ | 2.12, 2.13 | 0.21.x |
To get started with SBT, simply add the following to your build.sbt
file:
libraryDependencies += "io.kamon" %% "kamon-http4s" % "2.0.1"
Metrics and Tracing for http4s in 2 steps
The Server
def serve[F[_]](implicit Effect: Effect[F], EC: ExecutionContext) : Stream[F, StreamApp.ExitCode] =
for {
_ <- Stream.eval(Sync[F].delay(println("Starting Google Service with Client")))
client <- Http1Client.stream[F]()
service = GoogleService.service[F](middleware.client.KamonSupport(client)) (1)
exitCode <- BlazeBuilder[F]
.bindHttp(Config.server.port, Config.server.interface)
.mountService(middleware.server.KamonSupport(service)) (2)
.serve
} yield exitCode
- (1): The Kamon Middleware for the
Client
side. - (2): The Kamon Middleware for the
Server
side.
The Service
object GoogleService {
def service[F[_]: Effect](c: Client[F]): HttpService[F] = {
val dsl = new Http4sDsl[F]{}
import dsl._
HttpService[F] {
case GET -> Root / "call-google" =>
Ok(c.expect[String]("https://www.google.com.ar"))
}
}
}
Step 1: Add the Kamon Libraries
libraryDependencies ++= Seq(
"io.kamon" %% "kamon-core" % "2.1.0",
"io.kamon" %% "kamon-system-metrics" % "2.1.0",
"io.kamon" %% "kamon-prometheus" % "2.1.0",
"io.kamon" %% "kamon-http4s" % "2.0.1",
"io.kamon" %% "kamon-zipkin" % "2.1.0",
"io.kamon" %% "kamon-jaeger" % "2.1.0"
)
Step 2: Start Reporting your Data
Since version 2.0, Kamon reporters are started automatically through their default configuration. Now you can simply sbt run
the application and after a few seconds you will get the Prometheus metrics exposed on http://localhost:9095/ and message traces sent to Zipkin! The default configuration publishes the Prometheus endpoint on port 9095 and assumes that you have a Zipkin instance running locally on port 9411 but you can change these values under the kamon.prometheus
and kamon.zipkin
configuration keys, respectively.
Metrics
All you need to do is configure a scrape configuration in Prometheus. The following snippet is a minimal example that should work with the minimal server from the previous section.
A minimal Prometheus configuration snippet
------------------------------------------------------------------------------
scrape_configs:
- job_name: 'kamon-prometheus'
static_configs:
- targets: ['localhost:9095']
------------------------------------------------------------------------------
Once you configure this target in Prometheus you are ready to run some queries like this:
Those are the Server Metrics
metrics that we are gathering by default:
- active-requests: The the number active requests.
- http-responses: Response time by status code.
- abnormal-termination: The number of abnormal requests termination.
- service-errors: The number of service errors.
- headers-times: The number of abnormal requests termination.
- http-request: Request time by status code.
Now you can go ahead, make your custom metrics and create your own dashboards!
Traces
Assuming that you have a Zipkin instance running locally with the default ports, you can go to http://localhost:9411 and start investigating traces for this application. Once you find a trace you are interested in you will see something like this:
Clicking on a span will bring up a details view where you can see all tags for the selected span:
Enjoy!
That's it, you are now collecting metrics and tracing information from a http4s application.
Useful links:
Example of how to correctly configure the execution context by @cmcmteixeira