open-index/open-npm huggingface dataset:
npm package: @map-colonies/tracing
Description: A package that provides tracing capabilities using OpenTelemetry SDK
Latest version: 1.0.0

# Tracing
## Motive
This package provides tracing capabilities using OpenTelemetry SDK, making it easier to configure and work with distributed tracing in your applications.

## API documentation
Check the autogenerated documentation [here](https://mapcolonies.github.io/infra-packages/modules/_map_colonies_tracing.html).

## example
Below is a simple example of how to work with tracing. Please note that you need to manually install any auto-instrumentation library that you require.
The following code shows a simple example of how to work with tracing. please notice that you need to manually install any auto-instrumentation library that you require.

```typescript
import { Tracing } from '@map-colonies/tracing';
import { trace } from '@opentelemetry/api';

const tracing = new Tracing();

tracing.start();

const tracer = trace.getTracer('tracing-name')

const span = tracer.startSpan('some-action');

span.setAttribute('some-attribute', 'ITS VALUE');

// DO STUFF

span.end();

tracing.stop().then(() => console.log('done'));
```

Another way to initialize tracing with custom attributes:

```typescript
import { Tracing } from '@map-colonies/tracing';

const tracing = new Tracing({ 
  attributes: { 
    'service.version': '1.0.0', 
    'service.name': 'my-service-name' 
  } 
});
tracing.start();
...
```

## Configuration
### Common configuration
| name |allowed value| default value | description
|---|---|---|---|
|TELEMETRY_SERVICE_NAME|string|package.json name| The name of the service to put as attribute
|TELEMETRY_SERVICE_VERSION|string|package.json version| The version of the service to put as attribute
|TELEMETRY_HOST_NAME|string|`os.hostname()`|The value of the hostname attribute to use, will override the hostname

### Tracing configuration
| name |allowed value| default value | description 
|---|---|---|---|
|TELEMETRY_TRACING_ENABLED|'true', 'false'|'false'|Should Tracing be enabled
|TELEMETRY_TRACING_URL<span style="color:red">*</span>|string|http://localhost:4318/v1/traces|The URL to the OpenTelemetry Collector
|TELEMETRY_TRACING_RATIO|float|1|The amount of traces to sample (0-1)
|TELEMETRY_TRACING_DEBUG|'true', 'false'|'false'|Enable debug mode for tracing which enables opentelemetry debug log and console trace export

<span style="color:red">*</span> required (only when tracing is enabled).

## Related Packages
This package is part of the MapColonies infrastructure packages monorepo. For other telemetry-related functionality, see:
- `@map-colonies/semantic-conventions` - Semantic conventions for telemetry data
- `@map-colonies/tracing-utils` - Utilities for working with tracing