OpenTelemetry

Distributed tracing for GramIO via the OpenTelemetry API. Each incoming update becomes a root span, and each Telegram API call becomes a child span. Works with any OTEL-compatible backend (Jaeger, Grafana Tempo, Axiom, etc.) and integrates with Elysia webhooks.

Installation

npm install @gramio/opentelemetry

yarn add @gramio/opentelemetry

pnpm add @gramio/opentelemetry

bun add @gramio/opentelemetry

Usage

import { Bot } from "gramio";
import { opentelemetryPlugin } from "@gramio/opentelemetry";

const bot = new Bot(process.env.BOT_TOKEN!)
    .extend(opentelemetryPlugin({
        recordApiParams: true,
    }))
    .command("start", (context) => context.send("Hello!"));

await bot.start();

Trace Hierarchy

Each update produces a trace tree like the following:

gramio.update.message (CONSUMER)
  ├── telegram.api/sendMessage (CLIENT)
  ├── telegram.api/deleteMessage (CLIENT)
  └── custom spans via record()

Methods

record(name, fn)

Creates a custom child span inside the current update trace:

bot.command("heavy", async (context) => {
    await context.record("fetch-data", async () => {
        // expensive work tracked as its own span
    });
});

getCurrentSpan()

Returns the active OpenTelemetry span for the current update:

bot.on("message", (context) => {
    const span = context.getCurrentSpan();
    span?.addEvent("custom-event");
});

setAttributes(attrs)

Adds custom attributes to the current span:

bot.command("order", (context) => {
    context.setAttributes({
        "order.id": orderId,
        "order.total": total,
    });
});