Skip to content

docs: update README with API documentation and minor text improvements #102

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
CptSchnitz merged 1 commit into from
Jan 28, 2025
Merged

docs: update README with API documentation and minor text improvements #102

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 13 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@
This package goal is to make the experience of configuring and working with OpenTelemetry easier.

## [Manual for easy local grafana deployment](./localManual.md)

## API documentation
Check the autogenerated documentation [here](https://mapcolonies.github.io/telemetry/).

## example
Below are short examples for tracing and metrics. More examples are available at the [examples folder](examples/), and the various opentelemetry repos.
### Tracing
Expand All @@ -29,7 +33,7 @@ span.end();
tracing.stop().then(() => console.log('done'));
```

Another way for initialize tracing with custom resource:
Another way to initialize tracing with custom resource:

```typescript
import { Tracing } from '@map-colonies/telemetry';
Expand Down Expand Up @@ -59,8 +63,8 @@ metrics.stop().then(() => console.log('done'));
```

## Metrics middleware
The package provides a middleware for express that will automatically measure the duration of each request and the number of requests.
In addition the middleware can be configured to collect NodeJS metrics.
The package provides a middleware for Express that will automatically measure the duration of each request and the number of requests.
In addition, the middleware can be configured to collect NodeJS metrics.

```typescript
import { collectMetricsExpressMiddleware } from '@map-colonies/telemetry/prom-metrics';
Expand Down Expand Up @@ -92,17 +96,18 @@ Based on the [official OpenTelemetry conventions](https://opentelemetry.io/docs/
### Common configuration
| name |allowed value| default value | description
|---|---|---|---|
|TELEMETRY_SERVICE_NAME|string|from package.json| The service name
|TELEMETRY_SERVICE_VERSION|string| from package.json| The service version
|TELEMETRY_HOST_NAME|string|`os.hostname()`|The host name
|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
<br/>

### 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
|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).
<br/>
Expand All @@ -111,7 +116,7 @@ Based on the [official OpenTelemetry conventions](https://opentelemetry.io/docs/
|---|---|---|---|
|TELEMETRY_METRICS_ENABLED|'true', 'false'|'false'|Should Metrics be enabled|
|TELEMETRY_METRICS_URL<span style="color:red">*</span>|string|http://localhost:4318/v1/metrics|The URL to the OpenTelemetry Collector
|TELEMETRY_METRICS_INTERVAL|number|15000|The interval in miliseconds between sending data to the collector
|TELEMETRY_METRICS_INTERVAL|number|15000|The interval in milliseconds between sending data to the collector

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

Expand Down