# @usvc/tracer

> Distributed trace management package using Zipkin for use in an Express application.

Latest version **0.1.2** (published 2018-08-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install @usvc/tracer
pnpm add @usvc/tracer
yarn add @usvc/tracer
bun add @usvc/tracer
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.2 |
| Published | 2018-08-05 |
| First published | 2018-07-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 13.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | zephinzer |
| Maintainers | zephinzer |
| Keywords | b3, b3-propagation, context, distributed, express, microservices, middleware, opentracing, open-tracing, request, sampled, span-id, trace, trace-id, tracer, tracing, usvc, zipkin |

## Links

- npm: https://www.npmjs.com/package/@usvc/tracer
- Repository: https://github.com/zephinzer/ms
- Homepage: https://github.com/zephinzer/ms#readme
- Issues: https://github.com/zephinzer/ms/issues
- npm.io page: https://npm.io/package/@usvc/tracer

## Dependencies (4)

- [zipkin](https://npm.io/package/zipkin.md) ^0.13.0
- [express](https://npm.io/package/express.md) ^4.16.3
- [zipkin-transport-http](https://npm.io/package/zipkin-transport-http.md) ^0.14.0
- [zipkin-instrumentation-express](https://npm.io/package/zipkin-instrumentation-express.md) ^0.14.0

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 0.1.2 (latest) — 2018-08-05
- 0.1.1 — 2018-07-30
- 0.1.0 — 2018-07-30
- 0.0.3 — 2018-07-29
- 0.0.2 — 2018-07-28
- 0.0.1 — 2018-07-28

## README

# `@usvc/tracer`
Distributed trace management package using Zipkin for use in an Express application.

## Scope

- [x] Creation of a tracer
- [x] Allow for configuration of sample rate
- [x] Allow for configuration of headers sent to Zipkin service
- [x] Allow for configuration of Zipkin service URL
- [x] Allow for configuration of trace ID bit count

## Installation

```bash
npm i @usvc/tracer;
# OR
yarn add @usvc/tracer;
```

## Usage

```js
// es5
const {
  createTracer,
  getContextProviderMiddleware,
} = require('@usvc/tracer');

// es6
import {
  createTracer,
  getContextProviderMiddleware,
} from '@usvc/tracer';
```

### Basic

```js
const express = require('express');
// require module as per ^
const tracer = createTracer();
const app = express();
app.use(tracer.getExpressMiddleware());
// ...
```

### Full Configuration

```js
const express = require('express');
// require module as per ^
const tracer = createTracer({
  sampleRate: 1,
  headers: {},
  httpTimeout: 5.0,
  url: 'http://localhost:9411',
  traceId128bit: true,
});
const app = express();
app.use(tracer.getExpressMiddleware());
// ...
```

## API Documentaiton

### `createTracer(:options)`
Creates the tracer object. The `:options` parameter has the following schema:

| Key | Type | Defaults To | Description |
| --- | --- | --- | --- |
| `sampleRate` | Number | `1` | The frequency of which to sample requests - 1 means sample everything, 0 means sample nothing |
| `headers` | Object | `{}` | Additional headers to be sent to the Zipkin service - use this to add stuff like `X-Authorization` headers |
| `httpTimeout` | Number | `5.0` | Timeout in seconds for a call to the Zipkin service |
| `url` | URL | `http://localhost:9411` | The base URL of your Zipkin service |
| `traceId128Bit` | Boolean | `true` | Enables 128-bit length trace IDs |

The returned object has the following methods:

| Method | Description |
| --- | --- |
| `getContext()` | Retrieves the internally created context |
| `getExpressMiddleware()` | Retrieves an array of middlewares usable via `express().use(...)` |
| `getTracer()` | Retrieves the raw Zipkin tracer |

### `getContextProviderMiddleware(:options)`
Returns an Express middleware that adds a `.context` property to the Express Request object and passes it downstream. The `:options` has the following schema:

| Key | Type | Defaults To | Description |
| --- | --- | --- | --- |
| `context` | `Context<T>` | `undefined` | The context object retrievable via the `.getContext()` method of the object returned by `createTracer()`. Alternatively, can used alone. |

## Examples

`WIP`

## Development

`WIP`

## License

This package is licensed under the MIT license.

View the license at [LICENSE](./LICENSE).

## Changelog

### 0.1.x
#### 0.1.0
- Initial release

## Contributors

| Name | Email | Website | About Me |
| --- | --- | --- | --- |
| zephinzer | - | https://github.com/zephinzer | - |

# Cheers

---
_Source: https://npm.io/package/@usvc/tracer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._