# ArkeOpentelemetryEx

> **This package is under heavy development.** APIs may change without notice.

The go-to package for setting up OpenTelemetry in Arke applications. One dependency replaces seven — get traces (Phoenix, Cowboy, Ecto) and OTLP log export out of the box.

## Installation

Add the dependency to `mix.exs`:

```elixir
def deps do
  [
    {:arke_opentelemetry_ex, "~> 0.1.0"}
  ]
end
```

For releases, add the required OTP applications:

```elixir
def project do
  [
    releases: [
      my_app: [
        applications: [
          opentelemetry_exporter: :permanent,
          opentelemetry: :temporary
        ]
      ]
    ]
  ]
end
```

## Quick Start

1. Configure in `config/config.exs`:

```elixir
config :opentelemetry,
  resource: %{service: %{name: "my_service"}}

config :arke_opentelemetry_ex,
  ecto_repos: [[:my_app, :repo]]

config :logger,
  backends: [:console, ArkeOpentelemetryEx.LoggerBackend]
```

2. Set environment variables:

```
OTLP_ENDPOINT=https://collector:4317
OTLP_LOGS_ENDPOINT=https://collector:4318/v1/logs
```

3. Call `setup/0` in your `application.ex`:

```elixir
def start(_type, _args) do
  ArkeOpentelemetryEx.setup()

  children = [...]
  Supervisor.start_link(children, strategy: :one_for_one)
end
```

That's it. The package reads `OTLP_ENDPOINT` (gRPC, for traces) and `OTLP_LOGS_ENDPOINT` (HTTP, for logs) automatically.

## Overriding Defaults

The smart defaults cover the common case. Override any of them in `config/runtime.exs`:

```elixir
# Override trace exporter settings
config :opentelemetry_exporter,
  otlp_endpoint: "https://custom-collector:4317",
  otlp_protocol: :http_protobuf,
  otlp_headers: [{"x-api-key", "secret"}],
  otlp_compression: :gzip

# Override logger backend settings
config :logger, ArkeOpentelemetryEx.LoggerBackend,
  endpoint: "https://custom-collector:4318/v1/logs",
  level: :warning,
  batch_size: 200,
  flush_interval: 10_000
```

Explicit config always takes precedence over environment variables.

## Multi-tenancy

If `TENANT_ID` is set, the package automatically adds a `{"tenant", value}` header to both trace and log exports:

```
TENANT_ID=tenant_id_value
```

The header is merged with any existing headers and won't override an explicit `tenant` header.

## Disabling

Set `enabled: false` to turn off all tracing, instrumentation, and log export:

```elixir
config :arke_opentelemetry_ex,
  enabled: false
```

When disabled, `setup/0` is a no-op (OTP apps are not started, instrumentations are not attached) and the logger backend silently drops all log records. Defaults to `true`.

## Configuration Reference

### `:opentelemetry`

Standard opentelemetry SDK config. See [opentelemetry-erlang](https://github.com/open-telemetry/opentelemetry-erlang) docs.

| Key | Description |
|---|---|
| `:resource` | Resource attributes map (e.g. `%{service: %{name: "my_svc"}}`) |
| `:traces_exporter` | `:otlp` or `:none` |
| `:span_processor` | `:otel_batch_processor` or `:otel_simple_processor` |

### `:opentelemetry_exporter`

| Key | Description | Default |
|---|---|---|
| `:otlp_endpoint` | OTLP collector endpoint | `OTLP_ENDPOINT` env var |
| `:otlp_protocol` | `:grpc` or `:http_protobuf` | `:grpc` |
| `:otlp_headers` | Extra headers list | `[]` |
| `:otlp_compression` | `:gzip` or `nil` | `nil` |

### `ArkeOpentelemetryEx.LoggerBackend`

Configured via `config :logger, ArkeOpentelemetryEx.LoggerBackend`.

| Key | Description | Default |
|---|---|---|
| `:endpoint` | OTLP logs endpoint (HTTP) | `OTLP_LOGS_ENDPOINT` env var |
| `:level` | Minimum log level | `:info` |
| `:batch_size` | Records buffered before flush | `100` |
| `:flush_interval` | Milliseconds between flushes | `5000` |
| `:headers` | Extra headers list | `[]` |

### `:arke_opentelemetry_ex`

Package-specific options for telemetry instrumentation.

| Key | Description | Default |
|---|---|---|
| `:enabled` | Enable/disable all telemetry | `true` |
| `:ecto_repos` | List of Ecto telemetry prefixes | `[]` |
| `:exclude` | List of instrumentations to skip (`:cowboy`, `:phoenix`, `:ecto`) | `[]` |
| `:phoenix_adapter` | Phoenix adapter | `:cowboy2` |

## License

MIT