rtb-telemetry 0.7.5

Opt-in anonymous usage telemetry with pluggable sinks. Part of the phpboyscout Rust toolkit.
Documentation 
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

---
title: Cargo features and requirements
description: What remote-sinks turns on, what ships by default, the MSRV, and the runtime and dependencies the crate needs.
---

# Cargo features and requirements

## Features

| Feature | Default | What it adds |
|---|---|---|
| `remote-sinks` | off | `HttpSink`, `HttpSinkConfig`, `OtlpSink`, `OtlpSinkConfig` |

`default = []`, so there are no default features. A plain
`rtb-telemetry = "0.7"` gives you `NoopSink`, `MemorySink`, `FileSink`, the
consent module and the machine-ID derivation, and nothing that can reach
the network.

```toml
[dependencies]
rtb-telemetry = { version = "0.7", features = ["remote-sinks"] }
```

Turning `remote-sinks` on compiles in reqwest, url, secrecy, tonic and the
OpenTelemetry stack (`opentelemetry`, `opentelemetry_sdk`,
`opentelemetry-otlp`). That is a large dependency subtree to audit and to
build; leaving the feature off means none of it is compiled or linked at
all, not merely unused.

The `http_sink` and `otlp_sink` modules do not exist without the feature.
If `use rtb_telemetry::HttpSink` fails to resolve, the feature is off.

## Minimum supported Rust version

The minimum supported Rust version is 1.88, edition 2021, declared as
`rust-version = "1.88"` in `Cargo.toml`. The dependencies set that floor:
the crate requires `time` 0.3.55 or later, which declares
`rust-version = "1.88"`, and `tonic` 0.14, pulled in by `remote-sinks`,
declares the same. A dependency bump can raise the floor again.

Development in this repository pins an exact toolchain
(`rust-toolchain.toml`), and nothing here builds the crate on an older one,
so treat any version below the pin as untested.

## What the crate needs at runtime

- **A Tokio runtime.** `emit` and `flush` are `async`, and `FileSink` uses
  Tokio's filesystem API. The crate depends on `tokio` with the `full`
  feature set, so it is already in your tree.
- **TLS via rustls.** `reqwest` is pulled in with default features off and
  `rustls` on, so `HttpSink` does not need OpenSSL on the build host.
- **A readable machine ID, ideally.** `MachineId::derive` reads the host
  machine ID through `machine-uid` when the policy is `Enabled`. What
  happens when it cannot is covered in
  [Machine identity](../explanation/machine-identity.md).

## Always-on dependencies

`machine-uid`, `sha2`, `tokio`, `async-trait`, `serde`, `serde_json`,
`thiserror`, `miette`, `time`, `toml`, `uuid` and
[`rtb-redact`](https://redact.rust.phpboyscout.uk).

`rtb-redact` is not optional. It is what redaction is made of, and making
it optional would let a build silently drop the scrubbing step from the
sinks that write off-process.

## Safety

`src/lib.rs` carries `#![forbid(unsafe_code)]`. The crate contains no
`unsafe` blocks and cannot grow one without the compiler refusing.