aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 04a72034ced2846bc32a5639cc0c367b08cc095a (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
# Driver Tracing Library

A vendor-neutral tracing library for Akka-HTTP.

This library provides tracing directives for Akka-HTTP. It specifies
common client abstractions and implementations that may be used with
different tracing solutions, such as Google Stackdriver Tracing.

## Getting Started

Driver tracing is published to maven central as a standard Scala
library. Include it in sbt by adding the following snippet to your
build.sbt:

```scala
libraryDependencies += "xyz.driver" %% "tracing" % "0.0.1"
```

### Example

The library provides tracing directives which may be used to track and
report traces accross multiple, nested service calls.

```scala
import xyz.driver.tracing._
import xyz.driver.tracing.TracingDirectives._

val tracer = new LoggingTracer(println)

val route =
  // report how long any request to this service takes
  trace(tracer) {
    path("my-service-endpoint") {
      get {
        // include a sub-trace with a custom name
        trace(tracer, Some("complex-call")) {
          // do something that takes time
          complete("done")
        }
      }
    } ~
    path("proxy-service-endpoint") {
      // extract tracing headers so they may be injected into nested requests
      extractTraceHeaders{ headers =>
        // call external service with the existing parent tracing headers
        complete("done")
      }
    }
  }
```

## Tracing Backends
Various tracing aggregation backends are provided out of the box.

### Logging
The `LoggingTracer` simply logs any traces locally.

### Google Stackdriver Tracing
The `GoogleTracer` interacts with the Google Stack Driver API, as described here:
https://cloud.google.com/trace/docs/reference/v1/rest/v1/projects.traces#Trace

## Copying
Copyright 2017 Driver Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.