Packages

ex_gram

0.66.0
0.67.0 0.66.0 0.65.0 0.64.0 0.63.0 0.62.0 0.61.0 0.60.0 0.58.0 0.57.0 0.56.1 0.56.0 0.55.1 0.55.0 0.54.0 0.53.0 0.52.2 0.52.1 0.52.0 0.51.1 0.51.0 0.50.2 0.50.1 0.50.0 0.41.0 0.40.0 0.34.0 0.33.0 0.32.0 0.31.0 0.30.0 0.29.0 0.28.0 0.27.0 0.26.0 0.25.0 0.24.1 0.24.0 0.23.0 0.22.0 0.21.0 0.20.0 0.15.0 0.14.0 0.13.0 0.12.0 0.11.0 0.10.0 0.9.0 0.8.1 0.8.0 0.7.1 0.7.0 0.6.2 0.6.1 0.6.0 0.5.0 0.5.0-rc6 0.5.0-rc5 0.5.0-rc4 0.5.0-rc3 0.5.0-rc2

Telegram Bot API low level and framework

HexDocs

Current section

Files

Jump to
Readme
62 Versions
11 Dependencies
8 Dependants
Files
Activity
ex_gram guides opentelemetry.md
Raw

guides/opentelemetry.md 

# OpenTelemetry



ExGram emits [`:telemetry` events](telemetry.md) for update processing, handler execution, middleware, outbound API requests, and polling cycles. The [`opentelemetry_ex_gram`](https://github.com/rockneurotiko/opentelemetry_ex_gram) library attaches to those events and creates OpenTelemetry spans automatically.



## Installation



Add the library and the OTel SDK to your `mix.exs`:



```elixir

def deps do

  [

    {:opentelemetry_ex_gram, "~> 0.1"},

    {:opentelemetry, "~> 1.3"}

  ]

end

```



`opentelemetry_api`, `opentelemetry_telemetry`, and `opentelemetry_process_propagator` are pulled in as transitive dependencies.



## Setup



Call `OpentelemetryExGram.setup/0` once during application startup, before your bots are started:



```elixir

def start(_type, _args) do

  OpentelemetryExGram.setup()



  children = [ExGram, {MyBot, [method: :polling, token: token]}]

  Supervisor.start_link(children, strategy: :one_for_one)

end

```



You can also configure it using `OpentelemetryExGram.setup/1`. 



Available options:



| Option | Default | Description |

|---|---|---|

| `:span_prefix` | `"ExGram"` | Prefix for all span names |

| `:trace_polling` | `true` | Create spans for polling cycles |

| `:trace_middlewares` | `true` | Create spans for each middleware |

| `:trace_requests` | `true` | Create spans for outbound Telegram API calls |



## Span hierarchy



A typical update produces this span tree:



```text

{prefix}.update

  {prefix}.middleware   (one per middleware)

  {prefix}.handler

    {prefix}.request    (one per outbound API call)

```



OTel context is propagated automatically across all process boundaries, including async handlers.



## Testing



`OpentelemetryExGram.Test` provides a per-test setup helper that attaches the telemetry handler for a specific test bot and registers automatic cleanup:



```elixir

setup context do

  {bot_name, _} = ExGram.Test.start_bot(context, MyBot)

  OpentelemetryExGram.Test.setup(bot_name)

  {:ok, bot_name: bot_name}

end

```



> ### More information {: .info}

>

> For full documentation — span attributes, advanced options, and testing with

> [`opentelemetry_test_processor`](https://hex.pm/packages/opentelemetry_test_processor) — see the

> [`opentelemetry_ex_gram` repository](https://github.com/rockneurotiko/opentelemetry_ex_gram).