{"repo": "beamlens/beamlens", "files": {"README.md": {"c26b46059c0121289fb0cbf78c8760d2d5302ee5": {"t": 1785596401.870498, "n": 8125, "h": "0a8762b702268f54", "c": "**Early Development** — Ready for experimentation. Start with staging or low-risk services. We welcome feedback from early adopters.\n\n# Beamlens\n\nAdaptive runtime intelligence for the BEAM.\n\n[](https://hex.pm/packages/beamlens)\n[](https://hexdocs.pm/beamlens)\n[](LICENSE)\n\nMove beyond static supervision. Give your application the capability to self-diagnose incidents, analyze traffic patterns, and optimize its own performance.\n\n![\"Demo\"](\"assets/demo.gif\")
\n\n## Why Beamlens?\n\n**Static rules miss context.** Threshold alerts fire on symptoms, not causes. When memory spikes, you get an alert—but you still need to figure out whether it's a memory leak, ETS bloat, or a stuck process. Beamlens investigates the *why*.\n\n**External monitors miss internals.** APM tools see requests and traces, but they can't peer into ETS distributions, scheduler utilization, or allocator fragmentation. Beamlens captures the runtime state that external tools miss.\n\n**Manual debugging is reactive.** By the time you SSH in and attach a remote shell, the incident may have passed. Beamlens investigates while it happens, capturing the state you need for diagnosis.\n\n## Supported Providers\n\nBeamlens works with any LLM provider. Anthropic is the default. See the [providers guide](docs/providers.md) for configuration details.\n\n| Provider |\n|----------|\n| Anthropic |\n| OpenAI |\n| Google AI (Gemini) |\n| Google Vertex AI |\n| AWS Bedrock |\n| Azure OpenAI |\n| Ollama (Local) |\n| OpenRouter |\n| OpenAI Compatible APIs |\n\n## How It Works\n\nBeamlens lives inside your supervision tree. It captures runtime state and uses an LLM to explain *why* your metrics look the way they do.\n\n- **Production-safe**: All analysis is read-only. No side effects.\n- **Privacy-first**: Data stays in your infrastructure. You choose the LLM provider.\n- **Extensible**: Built-in skills + custom skills for your domain.\n- **Auto or on-demand**: Trigger manually, on schedule, or let the Anomaly skill auto-trigger on statistical anomalies.\n\n## Installation\n\n### Igniter (Recommended)\n\nInstall igniter:\n\n```bash\nmix archive.install hex igniter_new\n```\n\nInstall Beamlens:\n\n```bash\n# Choose your provider, model is optional\nmix igniter.install beamlens --provider openai --model \"gpt-5-mini\"\n```\n\nSupported providers: anthropic (default), openai, ollama, google-ai, vertex-ai, aws-bedrock, azure-openai, openrouter, openai-generic.\n\n### Manual\n\nAdd to `mix.exs`:\n\n```elixir\ndef deps do\n [\n {:beamlens, \"~> 0.3\"}\n ]\nend\n```\n\nAdd to your supervision tree in `application.ex`:\n\n```elixir\ndef start(_type, _args) do\n children = [\n # ... your other children\n Beamlens\n ]\n\n Supervisor.start_link(children, strategy: :one_for_one)\nend\n```\n\nYou can also configure which skills to enable:\n\n```elixir\n{Beamlens, skills: [\n Beamlens.Skill.Beam,\n {Beamlens.Skill.Anomaly, [collection_interval_ms: 60_000]}\n]}\n```\n\nConfigure your LLM provider. Set an API key for the default Anthropic provider:\n\n```bash\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n```\n\nOr configure a custom [provider](docs/providers.md) in your supervision tree:\n\n```elixir\n{Beamlens, client_registry: %{\n primary: \"Anthropic\",\n clients: [\n %{name: \"Anthropic\", provider: \"anthropic\",\n options: %{model: \"claude-haiku-4-5-20251001\"}}\n ]\n}}\n```\n\n## Usage\n\n**Run Beamlens** (from an alert handler, Oban job, or IEx):\n\n```elixir\n{:ok, result} = Beamlens.Coordinator.run(%{reason: \"memory alert...\"})\n```\n\n**Handle automatic insights**\n\nThe Anomaly skill is enabled by default. It learns your baseline, then auto-triggers investigations when it detects statistical anomalies.\n\n```elixir\n:telemetry.attach(\n \"beamlens-insights\",\n [:beamlens, :coordinator, :insight_produced],\n fn _event, _measurements, metadata, _config ->\n Logger.warning(\"Beamlens: #{metadata.insight.summary}\")\n end,\n nil\n)\n```\n\n## Built-in Skills\n\nBeamlens includes skills for common BEAM runtime monitoring:\n\n| Skill | Description | Default |\n|-------|-------------|:-------:|\n| `Beamlens.Skill.Beam` | BEAM VM health (memory, processes, schedulers, atoms, ports) | ✓ |\n| `Beamlens.Skill.Allocator` | Memory allocator fragmentation monitoring | ✓ |\n| `Beamlens.Skill.Anomaly` | Statistical anomaly detection with auto-trigger | ✓ |\n| `Beamlens.Skill.Ets` | ETS table monitoring (counts, memory, top tables) | ✓ |\n| `Beamlens.Skill.Gc` | Garbage collection statistics | ✓ |\n| `Beamlens.Skill.Logger` | Application log analysis (error rates, patterns) | ✓ |\n| `Beamlens.Skill.Os` | OS-level metrics (CPU, memory, disk via `os_mon`) | ✓ |\n| `Beamlens.Skill.Overload` | Message queue overload and bottleneck detection | ✓ |\n| `Beamlens.Skill.Ports` | Port and socket monitoring | ✓ |\n| `Beamlens.Skill.Supervisor` | Supervisor tree inspection | ✓ |\n| `Beamlens.Skill.Tracer` | Production-safe function tracing via Recon | ✓ |\n| `Beamlens.Skill.VmEvents` | System event monitoring (long GC, large heap, etc.) | ✓ |\n| `Beamlens.Skill.Ecto` | Database monitoring (requires `ecto_psql_extras`) | |\n| `Beamlens.Skill.Exception` | Exception tracking (requires `tower`) | |\n\n## Examples\n\n**Triggering from Telemetry**\n\n```elixir\n# In your Telemetry handler\ndef handle_event([:my_app, :memory, :high], _measurements, _metadata, _config) do\n # Trigger an investigation immediately\n {:ok, result} = Beamlens.Coordinator.run(%{reason: \"memory alert...\"})\n\n # Log the insights\n Logger.error(\"Memory Alert Diagnosis: #{inspect(result.insights)}\")\nend\n```\n\n**Creating Custom Skills**\n\nTeach Beamlens to understand your specific business logic. For example, if you use a GenServer to batch requests, generic metrics won't help—you need a custom skill.\n\n```elixir\ndefmodule MyApp.Skills.Batcher do\n @behaviour Beamlens.Skill\n\n # Shortened for brevity, see the Beamlens.Skill behaviour for full implementation details.\n\n @impl true\n def system_prompt do\n \"You are checking the Batcher process. Watch for 'queue_size' > 5000.\"\n end\n\n @impl true\n def snapshot do\n %{\n queue_size: MyApp.Batcher.queue_size(),\n pending_jobs: MyApp.Batcher.pending_count()\n }\n end\nend\n```\n\nSee the [Beamlens.Skill behaviour](https://hexdocs.pm/beamlens/Beamlens.Skill.html) for full custom skill documentation including callbacks.\n\n## FAQ\n\n\nIs it safe to run in production?
\n\nBeamlens is read-only and designed to run alongside your app. This is still early. Start with a low-risk service or staging, validate, then add more skills as you need.\n \n\n\nHow much does it cost to run?
\n\nBased on our test suite, a typical investigation uses around 10K tokens and costs about one to three cents with Haiku. If you're running continuous monitoring with auto-trigger at its default rate limit (3 per hour), expect roughly $1-3 per day.\n\nYou control the costs through model choice, which skills you enable, and how often investigations run. Auto-trigger is rate-limited by default to prevent runaway costs.\n \n\n\nWhich model do you recommend?
\n\nHaiku-level intelligence or higher. Haiku is a solid baseline for routine monitoring and runs well. Use a larger model for complex investigations.\n \n\n\nWhere does my data go?
\n\nBeamlens has no backend. Runtime data stays in your infrastructure and goes only to the LLM provider you configure. You bring your own API keys.\n \n\n## Get Involved\n\n- **[Early Access](https://forms.gle/1KDwTLTC1UNwhGbh7)** — Join the waitlist for the free web dashboard\n- **[Roadmap](https://github.com/orgs/beamlens/projects/1)** — See planned features including Phoenix integration and continuous monitoring\n- **[GitHub Issues](https://github.com/beamlens/beamlens/issues)** — Report bugs or request features\n- **[Partner with us](mailto:bradley@recursivesystem.dev)** — We're looking for early partners\n\n## License\n\nApache-2.0\n"}}}}