https://github.com/dahlia/logtape-otel
LogTape OpenTelemetry Sink
https://github.com/dahlia/logtape-otel
logtape opentelemetry otel
Last synced: 5 months ago
JSON representation
LogTape OpenTelemetry Sink
- Host: GitHub
- URL: https://github.com/dahlia/logtape-otel
- Owner: dahlia
- License: mit
- Created: 2024-08-24T09:59:59.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-26T04:18:54.000Z (9 months ago)
- Last Synced: 2025-06-09T16:50:25.480Z (5 months ago)
- Topics: logtape, opentelemetry, otel
- Language: TypeScript
- Homepage: https://jsr.io/@logtape/otel
- Size: 37.1 KB
- Stars: 15
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
@logtape/otel: LogTape OpenTelemetry Sink
=========================================
> [!NOTE]
> Since *@logtape/otel* package is now maintained along with
> the *@logtape/logtape* package, this repository is archived and no longer
> actively maintained.
>
> Please refer to the [LogTape] repository for the latest updates and
> developments.
[![JSR][JSR badge]][JSR]
[![npm][npm badge]][npm]
[![GitHub Actions][GitHub Actions badge]][GitHub Actions]
This package provides an [OpenTelemetry] sink for [LogTape]. It allows you to
send your LogTape logs to OpenTelemetry-compatible backends.
[JSR]: https://jsr.io/@logtape/otel
[JSR badge]: https://jsr.io/badges/@logtape/otel
[npm]: https://www.npmjs.com/package/@logtape/otel
[npm badge]: https://img.shields.io/npm/v/@logtape/otel?logo=npm
[GitHub Actions]: https://github.com/dahlia/logtape-otel/actions/workflows/main.yaml
[GitHub Actions badge]: https://github.com/dahlia/logtape-otel/actions/workflows/main.yaml/badge.svg
[OpenTelemetry]: https://opentelemetry.io/
[LogTape]: https://github.com/dahlia/logtape
Installation
------------
The package is available on [JSR] and [npm].
~~~~ bash
deno add @logtape/otel # for Deno
npm add @logtape/otel # for npm
pnpm add @logtape/otel # for pnpm
yarn add @logtape/otel # for Yarn
bun add @logtape/otel # for Bun
~~~~
Usage
-----
The quickest way to get started is to use the `getOpenTelemetrySink()` function
without any arguments:
~~~~ typescript
import { configure } from "@logtape/logtape";
import { getOpenTelemetrySink } from "@logtape/otel";
await configure({
sinks: {
otel: getOpenTelemetrySink(),
},
filters: {},
loggers: [
{ category: [], sinks: ["otel"], level: "debug" },
],
});
~~~~
This will use the default OpenTelemetry configuration, which is to send logs to
the OpenTelemetry collector running on `localhost:4317` or respects the `OTEL_*`
environment variables.
If you want to customize the OpenTelemetry configuration, you can specify
options to the [`getOpenTelemetrySink()`] function:
~~~~ typescript
import { configure } from "@logtape/logtape";
import { getOpenTelemetrySink } from "@logtape/otel";
await configure({
sinks: {
otel: getOpenTelemetrySink({
serviceName: "my-service",
otlpExporterConfig: {
url: "https://my-otel-collector:4317",
headers: { "x-api-key": "my-api-key" },
},
}),
},
filters: {},
loggers: [
{ category: [], sinks: ["otel"], level: "debug" },
],
});
~~~~
Or you can even pass an existing OpenTelemetry [`LoggerProvider`] instance:
~~~~ typescript
import { configure } from "@logtape/logtape";
import { getOpenTelemetrySink } from "@logtape/otel";
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';
import {
LoggerProvider,
SimpleLogRecordProcessor,
} from '@opentelemetry/sdk-logs';
const exporter = new OTLPLogExporter({
url: "https://my-otel-collector:4317",
headers: { "x-api-key": "my-api-key" },
});
const loggerProvider = new LoggerProvider();
loggerProvider.addProcessor(new SimpleLogRecordProcessor(exporter));
await configure({
sinks: {
otel: getOpenTelemetrySink({ loggerProvider }),
},
filters: {},
loggers: [
{ category: [], sinks: ["otel"], level: "debug" },
],
});
~~~~
For more information, see the documentation of the [`getOpenTelemetrySink()`]
function and [`OpenTelemetrySinkOptions`] type.
[`getOpenTelemetrySink()`]: https://jsr.io/@logtape/otel/doc/~/getOpenTelemetrySink
[`OpenTelemetrySinkOptions`]: https://jsr.io/@logtape/otel/doc/~/OpenTelemetrySinkOptions
[`LoggerProvider`]: https://open-telemetry.github.io/opentelemetry-js/classes/_opentelemetry_sdk_logs.LoggerProvider.html
Diagnostic logging
------------------
If you want to log diagnostic messages from the OpenTelemetry sink itself,
you can enable `diagnostics: true` in the sink options:
~~~~ typescript
import { configure, getConsoleSink } from "@logtape/logtape";
import { getOpenTelemetrySink } from "@logtape/otel";
await configure({
sinks: {
otel: getOpenTelemetrySink({ diagnostics: true }),
console: getConsoleSink(),
},
filters: {},
loggers: [
{ category: ["logtape", "meta"], sinks: ["console"], level: "debug" },
{ category: [], sinks: ["otel"], level: "debug" },
],
});
~~~~
This will log messages with the `["logtape", "meta", "otel"]` category.
These messages are useful for debugging the configuration of the OpenTelemetry
sink, but they can be verbose, so it's recommended to enable them only when
needed.
Changelog
---------
### Version 0.4.0
To be released.
- The minimum supported version of LogTape is now 0.12.0, which introduces
`"trace"` log level support.
### Version 0.3.0
Released on February 26, 2025.
- Now you can customize the body formatter. [[#1] by Hyeseong Kim]
- Added `BodyFormatter` type.
- Changed the type of `OpenTelemetrySinkOptions.messageType` to
`"string" | "array" | BodyFormatter | undefined` (was
`"string" | "array" | undefined`).
[#1]: https://github.com/dahlia/logtape-otel/pull/1
### Version 0.2.0
Released on August 26, 2024.
- The `OpenTelemetrySinkOptions` type is now an interface.
- Added `OpenTelemetrySinkOptions.messageType` option.
- Added `OpenTelemetrySinkOptions.objectRenderer` option. Now non-scalar
values are rendered using `util.inspect()` in Node.js/Bun and
`Deno.inspect()` in Deno by default.
### Version 0.1.0
Released on August 24, 2024. Initial release.