1 line
8.4 KiB
JSON
1 line
8.4 KiB
JSON
{"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<a href=\"https://screen.studio/share/w1qXNbUc\" target=\"_blank\"><img src=\"assets/demo.gif\" alt=\"Demo\" /></a>\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<details>\n<summary>Is it safe to run in production?</summary>\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</details>\n\n<details>\n<summary>How much does it cost to run?</summary>\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</details>\n\n<details>\n<summary>Which model do you recommend?</summary>\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</details>\n\n<details>\n<summary>Where does my data go?</summary>\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</details>\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"}}}} |