You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+3-2Lines changed: 3 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,8 +3,9 @@
3
3
# tracing-honeycomb
4
4
5
5
This repo contains the source code for:
6
-
-[`tracing-distributed`](tracing-distributed/README.md), which contains generic machinery for publishing distributed trace telemetry to arbitrary backends
7
-
-[`tracing-honeycomb`](tracing-honeycomb/README.md), which contains a concrete implementation that uses [honeycomb.io](https://honeycomb.io) as a backend
6
+
-[`tracing-distributed`](tracing-distributed/README.md), which contains generic machinery for publishing distributed trace telemetry to arbitrary backends.
7
+
-[`tracing-honeycomb`](tracing-honeycomb/README.md), which contains a concrete implementation that uses [honeycomb.io](https://honeycomb.io) as a backend.
8
+
-[`tracing-honeycomb`](tracing-jaeger/README.md), which contains a concrete implementation that uses [jaegertraing.io](https://www.jaegertracing.io/) as a backend.
Copy file name to clipboardExpand all lines: tracing-honeycomb/README.md
+29-20Lines changed: 29 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,21 +2,21 @@
2
2
3
3
# tracing-honeycomb
4
4
5
-
This crate provides:
6
-
- A tracing layer, `TelemetryLayer`, that can be used to publish trace data to honeycomb.io
7
-
- Utilities for implementing distributed tracing against the honeycomb.io backend
8
-
9
-
As a tracing layer, `TelemetryLayer` can be composed with other layers to provide stdout logging, filtering, etc.
10
-
11
5
## Usage
12
6
13
-
Add the following to your Cargo.toml to get started.
7
+
Add the following to your `Cargo.toml` to get started.
14
8
15
9
```toml
16
-
tracing-honeycomb = "0.1.0"
10
+
tracing-honeycomb = "0.2.0"
17
11
```
18
12
19
-
### Propagating distributed tracing metadata
13
+
This crate provides:
14
+
- A tracing layer, `TelemetryLayer`, that can be used to publish trace data to [honeycomb.io][].
15
+
- Utilities for implementing distributed tracing against the honeycomb.io backend.
16
+
17
+
As a tracing layer, `TelemetryLayer` can be composed with other layers to provide stdout logging, filtering, etc.
18
+
19
+
#### Propagating distributed tracing metadata
20
20
21
21
This crate provides two functions for out of band interaction with the `TelemetryLayer`
22
22
-`register_dist_tracing_root` registers the current span as the local root of a distributed trace.
@@ -27,48 +27,57 @@ Here's an example of how they might be used together:
27
27
2. A child of that span uses `current_dist_trace_ctx` to fetch the current `TraceId` and `SpanId`. It passes these values along with an RPC request, as metadata.
28
28
3. The RPC service handler uses the `TraceId` and remote parent `SpanId` provided in the request's metadata to register the handler function's span as a local root of the distributed trace initiated in step 1.
29
29
30
-
### Registering a global Subscriber
30
+
####Registering a global Subscriber
31
31
32
32
The following example shows how to create and register a subscriber created by composing `TelemetryLayer` with other layers and the `Registry` subscriber provided by the `tracing_subscriber` crate.
// NOTE: the underlying subscriber MUST be the Registry subscriber
47
-
letsubscriber=registry::Registry::default() // provide underlying span data store
51
+
letsubscriber=Registry::default() // provide underlying span data store
48
52
.with(LevelFilter::INFO) // filter out low-level debug tracing (eg tokio executor)
49
-
.with(tracing_subscriber::fmt::Layer::default()) // log to stdout
53
+
.with(fmt::Layer::default()) // log to stdout
50
54
.with(telemetry_layer); // publish to honeycomb backend
51
55
52
-
53
56
tracing::subscriber::set_global_default(subscriber).expect("setting global default failed");
54
57
```
55
58
56
-
### Testing
59
+
####Testing
57
60
58
61
Since `TraceCtx::current_trace_ctx` and `TraceCtx::record_on_current_span` can be expected to return `Ok` as long as some `TelemetryLayer` has been registered as part of the layer/subscriber stack and the current span is active, it's valid to `.expect` them to always succeed & to panic if they do not. As a result, you may find yourself writing code that fails if no distributed tracing context is present. This means that unit and integration tests covering such code must provide a `TelemetryLayer`. However, you probably don't want to publish telemetry while running unit or integration tests. You can fix this problem by registering a `TelemetryLayer` constructed using `BlackholeTelemetry`. `BlackholeTelemetry` discards spans and events without publishing them to any backend.
Copy file name to clipboardExpand all lines: tracing-honeycomb/README.tpl
+2-55Lines changed: 2 additions & 55 deletions
Original file line number
Diff line number
Diff line change
@@ -2,68 +2,15 @@
2
2
3
3
# {{crate}}
4
4
5
-
{{readme}}
6
-
7
5
## Usage
8
6
9
-
Add the following to your Cargo.toml to get started.
7
+
Add the following to your `Cargo.toml` to get started.
10
8
11
9
```toml
12
10
tracing-honeycomb = "{{version}}"
13
11
```
14
12
15
-
### Propagating distributed tracing metadata
16
-
17
-
This crate provides two functions for out of band interaction with the `TelemetryLayer`
18
-
- `register_dist_tracing_root` registers the current span as the local root of a distributed trace.
19
-
- `current_dist_trace_ctx` fetches the `TraceId`and`SpanId` associated with the current span.
20
-
21
-
Here's an example of how they might be used together:
22
-
1. Some span is registered as the global tracing root using a newly-generated `TraceId`.
23
-
2. A child of that span uses `current_dist_trace_ctx` to fetch the current `TraceId`and`SpanId`. It passes these values along with an RPC request, as metadata.
24
-
3. The RPC service handler uses the `TraceId`and remote parent `SpanId` provided in the request's metadata to register the handler function's span as a local root of the distributed trace initiated in step 1.
25
-
26
-
### Registering a global Subscriber
27
-
28
-
The following example shows how to create and register a subscriber created by composing `TelemetryLayer`with other layers and the `Registry` subscriber provided by the `tracing_subscriber` crate.
let telemetry_layer = mk_honeycomb_tracing_layer("my-service-name", honeycomb_config);
41
-
42
-
// NOTE: the underlying subscriber MUST be the Registry subscriber
43
-
let subscriber = registry::Registry::default() // provide underlying span data store
44
-
.with(LevelFilter::INFO) // filter out low-level debug tracing (eg tokio executor)
45
-
.with(tracing_subscriber::fmt::Layer::default()) // log to stdout
46
-
.with(telemetry_layer); // publish to honeycomb backend
47
-
48
-
49
-
tracing::subscriber::set_global_default(subscriber).expect("setting global default failed");
50
-
```
51
-
52
-
### Testing
53
-
54
-
Since `TraceCtx::current_trace_ctx`and`TraceCtx::record_on_current_span` can be expected to return `Ok` as long as some `TelemetryLayer` has been registered as part of the layer/subscriber stack and the current span is active, it's valid to `.expect` them to always succeed & to panic if they do not. As a result, you may find yourself writing code that fails if no distributed tracing context is present. This means that unit and integration tests covering such code must provide a `TelemetryLayer`. However, you probably don't want to publish telemetry while running unit or integration tests. You can fix this problem by registering a `TelemetryLayer` constructed using `BlackholeTelemetry`.`BlackholeTelemetry` discards spans and events without publishing them to any backend.
55
-
56
-
```rust
57
-
let telemetry_layer = mk_honeycomb_blackhole_tracing_layer();
58
-
59
-
// NOTE: the underlying subscriber MUST be the Registry subscriber
60
-
let subscriber = registry::Registry::default() // provide underlying span data store
61
-
.with(LevelFilter::INFO) // filter out low-level debug tracing (eg tokio executor)
62
-
.with(tracing_subscriber::fmt::Layer::default()) // log to stdout
63
-
.with(telemetry_layer); // publish to blackhole backend
64
-
65
-
tracing::subscriber::set_global_default(subscriber).expect("setting global default failed");
Copy file name to clipboardExpand all lines: tracing-honeycomb/src/lib.rs
+71-8Lines changed: 71 additions & 8 deletions
Original file line number
Diff line number
Diff line change
@@ -6,10 +6,73 @@
6
6
)]
7
7
8
8
//! This crate provides:
9
-
//! - A tracing layer, `TelemetryLayer`, that can be used to publish trace data to honeycomb.io
10
-
//! - Utilities for implementing distributed tracing against the honeycomb.io backend
9
+
//! - A tracing layer, `TelemetryLayer`, that can be used to publish trace data to [honeycomb.io][].
10
+
//! - Utilities for implementing distributed tracing against the honeycomb.io backend.
11
11
//!
12
12
//! As a tracing layer, `TelemetryLayer` can be composed with other layers to provide stdout logging, filtering, etc.
13
+
//!
14
+
//! ### Propagating distributed tracing metadata
15
+
//!
16
+
//! This crate provides two functions for out of band interaction with the `TelemetryLayer`
17
+
//! - `register_dist_tracing_root` registers the current span as the local root of a distributed trace.
18
+
//! - `current_dist_trace_ctx` fetches the `TraceId` and `SpanId` associated with the current span.
19
+
//!
20
+
//! Here's an example of how they might be used together:
21
+
//! 1. Some span is registered as the global tracing root using a newly-generated `TraceId`.
22
+
//! 2. A child of that span uses `current_dist_trace_ctx` to fetch the current `TraceId` and `SpanId`. It passes these values along with an RPC request, as metadata.
23
+
//! 3. The RPC service handler uses the `TraceId` and remote parent `SpanId` provided in the request's metadata to register the handler function's span as a local root of the distributed trace initiated in step 1.
24
+
//!
25
+
//! ### Registering a global Subscriber
26
+
//!
27
+
//! The following example shows how to create and register a subscriber created by composing `TelemetryLayer` with other layers and the `Registry` subscriber provided by the `tracing_subscriber` crate.
28
+
//!
29
+
//! ```no_run
30
+
//! use tracing_honeycomb::new_honeycomb_telemetry_layer;
31
+
//! use tracing_subscriber::prelude::*;
32
+
//! use tracing_subscriber::{filter::LevelFilter, fmt, registry::Registry};
//! let telemetry_layer = new_honeycomb_telemetry_layer("my-service-name", honeycomb_config);
44
+
//!
45
+
//! // NOTE: the underlying subscriber MUST be the Registry subscriber
46
+
//! let subscriber = Registry::default() // provide underlying span data store
47
+
//! .with(LevelFilter::INFO) // filter out low-level debug tracing (eg tokio executor)
48
+
//! .with(fmt::Layer::default()) // log to stdout
49
+
//! .with(telemetry_layer); // publish to honeycomb backend
50
+
//!
51
+
//! tracing::subscriber::set_global_default(subscriber).expect("setting global default failed");
52
+
//! ```
53
+
//!
54
+
//! ### Testing
55
+
//!
56
+
//! Since `TraceCtx::current_trace_ctx` and `TraceCtx::record_on_current_span` can be expected to return `Ok` as long as some `TelemetryLayer` has been registered as part of the layer/subscriber stack and the current span is active, it's valid to `.expect` them to always succeed & to panic if they do not. As a result, you may find yourself writing code that fails if no distributed tracing context is present. This means that unit and integration tests covering such code must provide a `TelemetryLayer`. However, you probably don't want to publish telemetry while running unit or integration tests. You can fix this problem by registering a `TelemetryLayer` constructed using `BlackholeTelemetry`. `BlackholeTelemetry` discards spans and events without publishing them to any backend.
57
+
//!
58
+
//! ```
59
+
//! use tracing_honeycomb::new_blackhole_telemetry_layer;
60
+
//! use tracing_subscriber::prelude::*;
61
+
//! use tracing_subscriber::{filter::LevelFilter, fmt, registry::Registry};
62
+
//!
63
+
//! let telemetry_layer = new_blackhole_telemetry_layer();
64
+
//!
65
+
//! // NOTE: the underlying subscriber MUST be the Registry subscriber
66
+
//! let subscriber = Registry::default() // provide underlying span data store
67
+
//! .with(LevelFilter::INFO) // filter out low-level debug tracing (eg tokio executor)
68
+
//! .with(fmt::Layer::default()) // log to stdout
69
+
//! .with(telemetry_layer); // publish to blackhole backend
0 commit comments