{"id":46129646,"url":"https://github.com/systemic-engineering/witness","last_synced_at":"2026-03-02T03:17:52.850Z","repository":{"id":338266863,"uuid":"1157215861","full_name":"systemic-engineering/witness","owner":"systemic-engineering","description":"Compile-time observability for Elixir with zero-duplication event tracking and OpenTelemetry integration","archived":false,"fork":false,"pushed_at":"2026-02-19T08:14:35.000Z","size":107,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-19T16:20:30.507Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/systemic-engineering.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-13T15:09:41.000Z","updated_at":"2026-02-19T08:13:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/systemic-engineering/witness","commit_stats":null,"previous_names":["systemic-engineer/witness","systemic-engineering/witness"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/systemic-engineering/witness","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemic-engineering%2Fwitness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemic-engineering%2Fwitness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemic-engineering%2Fwitness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemic-engineering%2Fwitness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/systemic-engineering","download_url":"https://codeload.github.com/systemic-engineering/witness/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemic-engineering%2Fwitness/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29991399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-02T03:17:52.654Z","updated_at":"2026-03-02T03:17:52.844Z","avatar_url":"https://github.com/systemic-engineering.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Witness\n[![CI](https://github.com/systemic-engineer/witness/actions/workflows/ci.yml/badge.svg)](https://github.com/systemic-engineer/witness/actions/workflows/ci.yml)\n[![Hexdocs.pm](https://img.shields.io/badge/hexdocs-online-blue)](https://hexdocs.pm/witness/)\n[![Hex.pm](https://img.shields.io/hexpm/v/witness.svg)](https://hex.pm/packages/witness)\n[![Hex.pm Downloads](https://img.shields.io/hexpm/dt/witness)](https://hex.pm/packages/witness)\n\nAn opinionated observability library for Elixir built on `:telemetry` with compile-time event registry, zero-duplication event tracking, and OpenTelemetry integration.\n\n## Features\n\n- **Zero Duplication**: Event names are written once at the emission site, handlers auto-attach\n- **Compile-Time Registry**: Events discovered automatically via module attributes\n- **Bounded Context Isolation**: Each context has separate observability configuration\n- **OpenTelemetry Integration**: Built-in OpenTelemetry handler for spans and events\n- **Logger Integration**: Emit structured log events through telemetry\n- **Type-Safe**: Comprehensive typespecs and compile-time validation\n\n## Installation\n\nAdd `witness` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:witness, \"~\u003e 0.3\"}\n  ]\nend\n```\n\n## Quick Start\n\n### 1. Define an observability context\n\n```elixir\ndefmodule MyApp.Users.Observability do\n  use Witness,\n    app: :my_app,\n    prefix: [:users]\nend\n```\n\n### 2. Use it in your modules\n\n```elixir\ndefmodule MyApp.Users.Service do\n  require MyApp.Users.Observability, as: O11y\n\n  def create_user(params) do\n    O11y.with_span [:create_user], %{user_id: params.id} do\n      # Business logic here\n      O11y.track_event([:validation, :passed], %{params: params})\n\n      result = do_create_user(params)\n\n      O11y.track_event([:user, :created], %{user_id: result.id})\n      result\n    end\n  end\nend\n```\n\n### 3. Add to supervision tree\n\n```elixir\ndefmodule MyApp.Users.Supervisor do\n  use Supervisor\n\n  def start_link(init_arg) do\n    Supervisor.start_link(__MODULE__, init_arg, name: __MODULE__)\n  end\n\n  def init(_init_arg) do\n    children = [\n      MyApp.Users.Observability,  # \u003c-- Add your observability context\n      # ... other children\n    ]\n\n    Supervisor.init(children, strategy: :one_for_one)\n  end\nend\n```\n\n## How It Works\n\n### Compile-Time Event Registry\n\nWhen you use `track_event/3` or `with_span/3` macros, Witness:\n\n1. Remembers the event name at compile time using module attributes\n2. Generates a `__observable__/0` callback that returns all events this module emits\n3. Turns the module into a `Witness.Source`\n\nWhen your observability context starts:\n\n1. It discovers all source modules via `:application.get_key(app, :modules)`\n2. Aggregates all events from all sources\n3. Attaches configured handlers to all events\n\nThis means **you never duplicate event names** - write them once where they're emitted, handlers attach automatically.\n\n### Bounded Contexts\n\nEach part of your application can have its own observability context with its own:\n\n- Event prefix (e.g., `[:users]`, `[:billing]`, `[:notifications]`)\n- Handler configuration\n- Active/inactive state\n\n```elixir\ndefmodule MyApp.Billing.Observability do\n  use Witness,\n    app: :my_app,\n    prefix: [:billing],\n    handler: [\n      {MyCustomHandler, config: :here},\n      Witness.Handler.OpenTelemetry\n    ]\nend\n```\n\n## Custom Handlers\n\nImplement the `Witness.Handler` behaviour:\n\n```elixir\ndefmodule MyApp.MetricsHandler do\n  @behaviour Witness.Handler\n\n  @impl true\n  def handle_event(event_name, measurements, metadata, config) do\n    # Your custom logic here\n    :ok\n  end\nend\n```\n\n## Logger Integration\n\nWitness provides a `Witness.Logger` module that emits structured log events through telemetry:\n\n```elixir\ndefmodule MyApp.Users.Service do\n  require MyApp.Users.Observability, as: O11y\n  require Witness.Logger\n\n  def create_user(params) do\n    Witness.Logger.info(O11y, \"Creating user\", user_id: params.id)\n\n    case do_create_user(params) do\n      {:ok, user} -\u003e\n        Witness.Logger.info(O11y, \"User created successfully\", user_id: user.id)\n        {:ok, user}\n\n      {:error, reason} -\u003e\n        Witness.Logger.error(O11y, \"User creation failed\", reason: reason)\n        {:error, reason}\n    end\n  end\nend\n```\n\n### Built-in Handler\n\nUse `Witness.Handler.Logger` to log telemetry events:\n\n```elixir\ndefmodule MyApp.Users.Observability do\n  use Witness,\n    app: :my_app,\n    prefix: [:users],\n    handler: [\n      {Witness.Handler.Logger, level: :info},\n      Witness.Handler.OpenTelemetry\n    ]\nend\n```\n\nThe handler automatically:\n- Logs events at the appropriate level (`:debug`, `:info`, `:warning`, `:error`, etc.)\n- Formats spans with duration and status\n- Includes structured metadata\n- Respects per-event log levels\n\n### Available Log Levels\n\n- `Witness.Logger.debug/3` - Debug-level logs\n- `Witness.Logger.info/3` - Info-level logs\n- `Witness.Logger.notice/3` - Notice-level logs\n- `Witness.Logger.warning/3` - Warning-level logs\n- `Witness.Logger.error/3` - Error-level logs\n- `Witness.Logger.critical/3` - Critical-level logs\n- `Witness.Logger.alert/3` - Alert-level logs\n- `Witness.Logger.emergency/3` - Emergency-level logs\n\n## Configuration\n\n### Context Configuration\n\n```elixir\nuse Witness,\n  app: :my_app,              # Required: OTP application name\n  prefix: [:my_context],      # Required: Event name prefix\n  active: true,               # Optional: Enable/disable (default: true)\n  handler: [...],             # Optional: List of handlers (default: [Witness.Handler.OpenTelemetry])\n  sources: [...],             # Optional: Explicit source modules (default: auto-discover)\n  extra_events: [...],        # Optional: Additional events not tracked by sources\n  store: {Witness.Store.Mnesia, []}  # Optional: Persistent event store (default: nil)\n```\n\n### Event Persistence\n\nWitness supports pluggable persistent storage via the `:store` option. Events flowing\nthrough the telemetry pipeline can be written to any backend that implements the\n`Witness.Store` behaviour.\n\nThe built-in backend is `Witness.Store.Mnesia`:\n\n```elixir\ndefmodule MyApp.Users.Observability do\n  use Witness,\n    app: :my_app,\n    prefix: [:users],\n    store: {Witness.Store.Mnesia, []}\nend\n```\n\nFor disc-backed persistence across restarts:\n\n```elixir\nstore: {Witness.Store.Mnesia, storage_type: :disc_copies}\n```\n\nQuery persisted events with `Witness.Store.Mnesia.list_events/3`:\n\n```elixir\n# All events\n{:ok, events} = Witness.Store.Mnesia.list_events(MyApp.Users.Observability, [], [])\n\n# Filtered\n{:ok, events} = Witness.Store.Mnesia.list_events(MyApp.Users.Observability,\n  [after: cutoff_ts, event_name: [:user, :created], limit: 50],\n  []\n)\n```\n\n#### Custom Store Backends\n\nImplement `Witness.Store` to use any storage system:\n\n```elixir\ndefmodule MyApp.Store.Postgres do\n  @behaviour Witness.Store\n\n  @impl true\n  def store_event(event_name, attributes, meta, context, config) do\n    # Write to Postgres\n    :ok\n  end\n\n  @impl true\n  def list_events(context, query_opts, config) do\n    # Query from Postgres\n    {:ok, []}\n  end\n\n  @impl true\n  def child_spec(config) do\n    %{id: __MODULE__, start: {__MODULE__, :start_link, [config]}}\n  end\nend\n```\n\n### Runtime Configuration\n\nYou can also configure contexts at runtime via application config:\n\n```elixir\n# config/runtime.exs\nconfig :my_app, MyApp.Users.Observability,\n  active: System.get_env(\"OBSERVABILITY_ENABLED\", \"true\") == \"true\"\n```\n\n## Pattern: Zero Duplication\n\n**Before (traditional telemetry):**\n\n```elixir\n# In your code\n:telemetry.execute([:my_app, :users, :created], %{user_id: id}, %{})\n\n# Somewhere else, you have to remember the exact event name\n:telemetry.attach(\"my-handler\", [:my_app, :users, :created], \u0026handle/4, nil)\n```\n\n**After (Witness):**\n\n```elixir\n# In your code\nO11y.track_event([:created], %{user_id: id})\n\n# Handlers attach automatically - no duplication!\n```\n\n## Comparison with Raw Telemetry\n\n| Feature | Raw :telemetry | Witness |\n|---------|---------------|---------|\n| Event duplication | Manual sync required | Zero duplication |\n| Event discovery | Manual registration | Automatic at compile-time |\n| Handler attachment | Manual per-event | Automatic per-context |\n| Bounded contexts | Manual convention | Built-in structure |\n| Type safety | Limited | Comprehensive specs |\n| OpenTelemetry | Manual integration | Built-in handler |\n\n## License\n\nThis project is licensed under the [Hippocratic License 3.0](LICENSE) - an ethical open source license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystemic-engineering%2Fwitness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsystemic-engineering%2Fwitness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystemic-engineering%2Fwitness/lists"}