logfire-sdk 6.0.0b2__py3-none-any.whl

_logfire_sdk/logfire/.agents/skills/logfire-evals/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: logfire-evals
+description: Run offline Python (`pydantic_evals`) or Node.js (`logfire/evals`) evaluations and review them in Logfire. Also redirect existing Braintrust `Eval()` suites. Use for eval setup, test datasets, AI scoring, agent checks, LLM judges, Braintrust migration, or Logfire Datasets & Experiments. Not for live traffic or infrastructure monitoring.
+---
+
+# Evaluate AI code with Logfire
+
+## How This Works
+
+Python's `pydantic_evals` and Node.js's `logfire/evals` run a task against cases, apply evaluators, and return a report. An active Logfire or OpenTelemetry provider may export inputs and outputs even if this skill did not configure it. Intentional upload needs `logfire.configure()` in Python or a configured Node.js exporter.
+
+Span-based evaluators inspect the task's OpenTelemetry span tree. Without working Logfire instrumentation, Python reports "No span tree available"; Node.js `HasMatchingSpan` can produce no evaluator result at all. Treat either signal as a setup failure, not evidence about the agent.
+
+## Step 1: Check for an Existing Braintrust Suite First
+
+Cheap check, before anything else: does this repo already have an existing Braintrust suite — actual `Eval(...)` calls or `from braintrust import Eval` in source, not just a `braintrust` dependency listed without any real usage? This path needs **no CLI auth at all** — don't run Step 2 for it. The compatibility endpoint is documented only for Logfire Cloud US and EU; for any other supplied origin, use the native evaluation path instead.
+
+Keep the existing `Eval()` code (Python `braintrust>=0.30.1` / TypeScript `braintrust>=3.24.0` — verified versions) and redirect its next run to Logfire by changing environment variables only, no `pydantic_evals` involved:
+
+```bash
+export BRAINTRUST_APP_URL="https://logfire-us.pydantic.dev/v1/braintrust"  # EU: logfire-eu.pydantic.dev
+export BRAINTRUST_API_KEY="<logfire-project-api-key>"                     # Settings -> API Keys
+unset BRAINTRUST_API_URL BRAINTRUST_PROXY_URL  # these override the endpoint above if set — the #1 "it still hit Braintrust" cause
+```
+
+The destination project's API key needs `project:write_otlp` and `project:read_datasets`: the SDK writes the run, then reads experiment metadata for its summary. An ingest-only write token fails with `403`.
+
+This **compatibility preview** covers inline/callable data, local tasks and scorers, multiple scores, one label per name, and normal summary finalization. It excludes Braintrust-hosted resources, BTQL, the model proxy, server-side scoring, and post-finalization feedback. Rust, `summarize_scores=False`, and manual `flush()` without comparison do not request the summary needed for projection. See the [full coverage and concept mapping](https://pydantic.dev/docs/logfire/get-started/comparisons/migrate-from-braintrust/).
+
+Skip straight to Step 5 (Verify) — the SDK's own printed result URL also opens directly in Logfire, and nothing else here (auth, dataset definition) applies to this path.
+
+**No existing Braintrust suite? Continue to Step 2 now**, before the more detailed identification in Step 3 — nothing past this point requires knowing the function/agent or dataset shape yet.
+
+## Step 2: Authenticate When the Run Needs Logfire
+
+For an explicitly local-only run without span evaluators, use a fresh process that neither preloads nor imports application telemetry; omit Python's `logfire.configure()` and any Node.js exporter bootstrap. If the task configures an exporter and has no documented disable switch, stop rather than claiming local-only. Uploading, hosted datasets, and span evaluators require Logfire authentication to the exact project.
+
+For a Logfire-backed run, use [Authenticate and Select the Exact Project](https://pydantic.dev/.well-known/agent-skills/logfire-instrumentation/references/auth.md) to derive the CLI target from the supplied Logfire URL and run its target-aware `whoami` check with a verified CLI path — for JS/TS projects without `uv`, use the external-prefix npm fallback instead of plain `npx`, which can execute a repository-local binary. Skip to Step 3 if that already reports the right project and resolved `--region` or `--base-url` target; otherwise, continue through the full authentication and project-selection sequence there. This CLI flow is for `logfire.configure()`; Step 3's hosted-dataset operations use a separate API key with different scopes.
+
+
+## Step 3: Detect What to Evaluate
+
+Identify the real task and any dataset. Follow repository package, test, and dependency conventions. For a first eval, prefer 3-5 cases from tests, schemas, examples, or synthetic fixtures, with deterministic checks for defined behavior. Do not copy the example unless it fits, replace an eval framework, or refactor unrelated code. Without a runnable task or safe expected behavior, ask one focused question instead of inventing either.
+
+- **In-code dataset**: a Python module using `pydantic_evals`, or a Node.js module using `logfire/evals`. This is the default for an agent-driven workflow.
+- **Hosted/managed dataset**: cases live in the Logfire UI, edited by non-engineers, pulled/pushed via a separate `LogfireAPIClient` (`from logfire.experimental.api_client import LogfireAPIClient`). Hosted inputs and outputs must be JSON objects; scalar roots accepted by code-defined datasets are rejected. `client.get_dataset(name)` with no type arguments returns a raw dict, not something `push_dataset` or `.evaluate_sync()` can take — pass the input/output (and metadata, if used) types to get back a real `pydantic_evals.Dataset`: `client.get_dataset(name, MyInputType, MyOutputType)`. If the stored dataset contains custom evaluators, also pass their classes with `custom_evaluator_types=[MyEvaluator]` (and custom report evaluators with `custom_report_evaluator_types=[...]`) so they can be deserialized. Push with `client.push_dataset(dataset)`. This needs its own API key from **Settings → API Keys** (scoped `project:read_datasets`/`project:write_datasets`), not Step 2's CLI auth flow. Only relevant if the user specifically wants case editing outside code.
+
+## Step 4: Define the Dataset and Run It
+
+Use the repository's existing package manager and lockfile. Install only the missing integration for its language.
+
+### Python
+
+Add `pydantic-evals[logfire]` with the detected Python manager: `uv add`, `poetry add`, or `pdm add`. For a pip/requirements project, update its declared requirements and install from that file; do not introduce a second manager or lockfile.
+
+```python
+import logfire
+from pydantic_evals import Case, Dataset
+from pydantic_evals.evaluators import EqualsExpected, IsInstance
+
+logfire.configure()  # omit only in the isolated local-only process described above
+
+def classify_sentiment(text: str) -> str:
+    return 'positive' if 'love' in text else 'negative'
+
+
+dataset = Dataset[str, str, None](
+    name='sentiment-eval',
+    cases=[
+        Case(name='positive', inputs='I love this', expected_output='positive'),
+        Case(name='negative', inputs='This is terrible', expected_output='negative'),
+    ],
+    evaluators=[EqualsExpected(), IsInstance(type_name='str')],
+)
+
+report = dataset.evaluate_sync(classify_sentiment)  # or `await dataset.evaluate(...)`
+report.print(include_input=True, include_output=True)
+```
+
+Use `logfire[datasets]` instead only when the task specifically needs the hosted-dataset API from Step 3.
+
+### JavaScript or TypeScript on Node.js
+
+Do not apply this section to Deno, Bun, browsers, or workers; their exporter setup is not validated by this skill.
+
+Add `logfire` and `@pydantic/logfire-node` with the manager selected by the existing lockfile: `pnpm add`, `yarn add`, `bun add`, or `npm install`. Do not introduce a second lockfile.
+
+Configure Logfire before loading the task. Reuse an existing instrumentation entry point rather than configuring it twice.
+
+```ts
+import * as logfire from '@pydantic/logfire-node'
+import { Case, Dataset, EqualsExpected, renderReport } from 'logfire/evals'
+
+logfire.configure()
+
+const classifySentiment = (text: string) => (text.includes('love') ? 'positive' : 'negative')
+const dataset = new Dataset<string, string>({
+  name: 'sentiment-eval',
+  cases: [new Case({ name: 'positive', inputs: 'I love this', expectedOutput: 'positive' })],
+  evaluators: [new EqualsExpected()],
+})
+
+await dataset.evaluate(classifySentiment).then((report) => {
+  console.log(renderReport(report, { includeInput: true, includeOutput: true }))
+}).finally(() => logfire.shutdown({ timeoutMillis: 5000 }))
+```
+
+Other built-ins include `Equals`, `Contains`, `IsInstance`, `MaxDuration`, `HasMatchingSpan`, and `LLMJudge`. Node.js custom evaluators extend `Evaluator`, and `LLMJudge` needs a judge callback. Use `@pydantic/logfire-node/datasets` only for hosted datasets.
+
+### Smoke test before a paid or full run
+
+**Before running the full dataset, run a smoke test on 2-3 cases** if the dataset is large or uses `LLMJudge` or any evaluator that makes billed model calls. This catches setup errors before they multiply cost across the dataset.
+
+Python:
+
+```python
+smoke = Dataset(
+    name=dataset.name,
+    cases=dataset.cases[:3],
+    evaluators=dataset.evaluators,
+    report_evaluators=dataset.report_evaluators,
+)
+smoke_report = smoke.evaluate_sync(classify_sentiment)
+smoke_report.print(include_input=True, include_output=True)
+```
+
+Node.js:
+
+```ts
+const smoke = new Dataset({
+  name: dataset.name,
+  cases: dataset.cases.slice(0, 3),
+  evaluators: dataset.evaluators,
+  reportEvaluators: dataset.reportEvaluators,
+})
+await smoke.evaluate(classifySentiment).then((report) => {
+  console.log(renderReport(report, { includeInput: true, includeOutput: true }))
+}).finally(() => logfire.shutdown({ timeoutMillis: 5000 }))
+```
+
+Confirm the smoke run has zero unexpected errors and the assertions that should pass do. Then, if the full dataset is large or uses paid model calls, tell the user the case count and which evaluators will make model calls, and get explicit confirmation before running the full dataset — don't run an expensive full pass on the strength of a clean smoke test alone without saying so.
+
+The remaining details in this section are Python-specific. Custom evaluators inherit `Evaluator` and implement `evaluate`; use `@dataclass` for configurable fields and portable serialization. Case names must be unique within a dataset. The evaluators reached for most:
+
+| Evaluator | Checks |
+|-----------|--------|
+| `Equals(value)` / `EqualsExpected()` | Exact match against a literal / `expected_output` (no-op if `expected_output` is unset — don't rely on it silently catching that) |
+| `IsInstance(type_name)` | Output's type matches by name |
+| `LLMJudge(rubric, model=None, score=False)` | Subjective or rubric-based judgment; makes billed model requests, so validate the rubric against human-reviewed examples before treating it as a quality gate |
+| `ToolCorrectness(expected_tools, ...)` | Which tools an agent called — reads the span tree, so needs Step 2's `logfire.configure()` to work at all, not just to upload |
+
+Also available: `Contains`, `MaxDuration`, `TrajectoryMatch`, `ArgumentCorrectness`, `MaxToolCalls`, `MaxModelRequests` — same span-tree dependency as `ToolCorrectness` for the tool/trajectory ones; see `pydantic_evals.evaluators` for the full set. These five agentic (span-based) evaluators need `pydantic-evals>=2.4.0` — on an older pin, check `pyproject.toml`/`uv.lock` and upgrade before reaching for them, since the import itself is what fails, not a silent no-op.
+
+The `Python` evaluator (arbitrary code execution) was removed for security reasons — don't reach for it even if an older example references it.
+
+If editing a hosted dataset: `client.push_dataset(dataset)` **overwrites** server-side evaluators on every push, including removing ones you deleted locally — don't push a stale local copy over a dataset others have edited in the UI.
+
+## Step 5: Verify
+
+A report printing to the terminal isn't proof it reached Logfire — confirm the run actually landed. **Never report a case as passed, a score, or a run as complete without having actually checked it in this session** — if a run fails, cancels, or produces no scores, report that failure plainly; never substitute an invented score or a manual guess at what the result "should" be.
+
+**Came from the Step 1 Braintrust path (Step 2 skipped)?** There's no `whoami`-resolved project to look up here — use the SDK's own printed result URL instead, which already opens directly in the right Logfire project. Confirm the same things below (completion, pass mix, case detail) from that page rather than searching by name.
+
+1. **Query for the run directly, if a Logfire MCP server or API is connected** — the root span for a run is named `evaluate {name}` and carries `gen_ai.operation.name = 'experiment'`, `dataset_name`, and `task_name` attributes; find the most recent one matching your dataset's name and confirm `logfire.experiment.metadata` shows the case count and pass rate you expect. Otherwise, open **AI Evaluations → Datasets & Experiments → Experiments** in Logfire for the exact project from Step 2, and find the run by name/timestamp.
+2. **Read the Overview tab (or the queried metadata) first**: completion count, assertion pass mix, task errors, average duration. **If completion says "Not reported,"** the run sent case data but never signaled it finished — treat that as a broken run, not a passing one.
+3. **Open the Cases tab**, starting from Needs Review / Failed / Errors, not the full list.
+4. **Drill into a failing case's trace in Live view** for the actual evidence, rather than trusting the summary score alone.
+5. **Fix and re-run** until the cases that should pass do, and any tool-call/trajectory checks show real span data, not "No span tree available."
+
+Close with a final report built from what you just confirmed — the run name, exact case count and pass rate you queried, and which evaluators ran — not a template. **Include the direct link to this experiment** (the SDK's own printed result URL, or the Datasets & Experiments page you opened it from), so the user can see the run without having to ask where to look.

_logfire_sdk/logfire/.agents/skills/logfire-infrastructure/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: logfire-infrastructure
+description: Monitor hosts, Docker containers, Kubernetes clusters, database/queue/cache servers, and cloud-provider metrics with Pydantic Logfire — no application code required. Use this skill whenever the user asks to "monitor my host/server/VM", "monitor my Docker containers", "monitor my Kubernetes cluster", "send infrastructure metrics to Logfire", "watch my database/Postgres/Redis/MongoDB/Kafka", "collect cloud metrics" (AWS/GCP), or mentions the OpenTelemetry Collector in the context of Logfire. This is infrastructure only — for instrumenting APPLICATION CODE (traces, logs, AI/agent spans) use the logfire-instrumentation skill instead.
+---
+
+# Monitor Infrastructure with Logfire
+
+Do **not** use this skill for application-level traces, logs, or AI/agent spans — that's `logfire-instrumentation`. The two compose: a full setup often runs both.
+
+## How This Works
+
+The OpenTelemetry Collector ships host, container, cluster, and infrastructure-service metrics to Logfire with **no application code changes** — Logfire is a fully compliant OTel backend and ingests standard OTLP traces, logs, and metrics from it (one narrow exception noted in the [collector reference](./references/collector/host-and-infra-metrics.md)), so the Collector is the entire mechanism. This is optional and is an advanced tool: if the user only wants their app's own traces, `logfire-instrumentation`'s language SDKs are enough on their own.
+
+## Step 1: Authenticate and Select the Exact Project
+
+Do not open, read, or run any infrastructure config file (`docker-compose.yml`, a Kubernetes manifest, or similar) until `whoami` confirms you're authenticated to the right project — nothing about this step requires knowing what's being monitored. Auth is also the one step that can block on a human (browser sign-in), so starting it first means that wait begins on turn one, not after Step 2's detection work.
+
+Use [Authenticate and Select the Exact Project](https://pydantic.dev/.well-known/agent-skills/logfire-instrumentation/references/auth.md) to derive the CLI target from the supplied Logfire URL and run its target-aware `whoami` check with a verified CLI path — for JS/TS projects without `uv`, use the external-prefix npm fallback instead of plain `npx`, which can execute a repository-local binary. Skip to Step 2 if that already reports the right project and resolved `--region` or `--base-url` target; otherwise, continue through the full authentication and project-selection sequence there, including its safe handoff for the write credential created by `projects use`.
+
+
+## Step 2: Identify What to Monitor
+
+Detect the infrastructure actually in play, don't assume:
+
+- **Host/VM**: monitoring the machine itself (CPU, memory, disk, network, load).
+- **Docker**: read `docker-compose.yml` / `Dockerfile`s for running containers.
+- **Kubernetes**: look for manifests, a `kubeconfig`, or `kubectl` context.
+- **Database/queue/cache servers**: read `docker-compose.yml` / `pyproject.toml` / `package.json` for Postgres, MySQL, Redis, MongoDB, Kafka, RabbitMQ, Nginx, Apache, Elasticsearch, or Memcached.
+- **Cloud provider**: GCP or AWS metrics (Cloud Monitoring, CloudWatch, ECS), when the user names the provider or the app clearly runs there.
+
+More than one can apply at once — a single Collector can run multiple receivers in parallel pipelines.
+
+## Step 3: Configure the Collector
+
+Follow the [collector reference](./references/collector/host-and-infra-metrics.md) for the receiver(s) identified in Step 2 — it covers the shared exporter setup, then a dedicated section per source: host metrics, Docker, Kubernetes, database/queue/cache servers, and cloud-provider metrics, each with the exact receiver name, a working config, and the caveats that actually bite (Docker socket permissions, API version pinning, `host.docker.internal` vs `localhost`, IAM permissions, ADOT vs. Contrib collector images).
+
+Set the same service & resource metadata conventions the [collector reference](./references/collector/host-and-infra-metrics.md) describes — `host.name`, `service.name`, `service.instance.id` — so data groups correctly across the Hosts, Kubernetes, and Metrics pages.
+
+Before starting or restarting the Collector, validate the config file — a receiver typo or bad indentation should surface as a validation error, not a Collector that starts, logs nothing useful, and silently drops the pipeline:
+
+```bash
+otelcol-contrib validate --config=collector-config.yaml
+# or, for the core (non-Contrib) distribution: otelcol validate --config=...
+```
+
+If neither binary is on `PATH`, inspect the running Collector container (for example with `kubectl exec`) or use the deployment-specific validation command from the image entrypoint, systemd unit, or Helm chart. `docker compose config` or `kubectl get pod <name> -o yaml` can show the command when it is explicitly configured.
+
+## Step 4: Verify
+
+Wiring a receiver isn't done when the Collector starts cleanly — confirm the data actually reached the right page for the right host/container/cluster, not just that something arrived. **Never report a metric as "arrived" without having queried for it in this same session** — a plausible-sounding summary that wasn't checked is worse than saying you couldn't verify.
+
+1. **Restart the Collector** after any config change (having validated it, above).
+2. **Query for the exact resource you configured, not just any data on the page.** If a Logfire MCP server or API is connected in this session, query for the specific `host.name` / container / cluster you set in Step 3 within the last few minutes — a query that returns zero rows for that exact identifier means it didn't land, even if the page shows data from something else. Otherwise, open the specific product page — **Hosts**, **Docker**, or **Kubernetes** — or the **Metrics** explorer for database/queue/cache/cloud sources, and look for that same exact identifier.
+3. **If nothing appears**, check in order: the exporter endpoint/region and write token, that the receiver is in an active pipeline (not defined but never referenced under `service.pipelines`), and that resource attributes (`host.name`, `service.name`) are set — the [reference's own Verify section](./references/collector/host-and-infra-metrics.md) has the full troubleshooting path.
+4. **Fix and re-check** until the specific source is visible, not just "some" data.
+
+Close with a final report built from what you just confirmed — org/project/region from `whoami`, which receiver(s) are active, and the exact host/container/cluster identifier you verified — not a template. **Include a direct link to the relevant view** (`/hosts`, `/docker`, `/kubernetes`, or `/metrics`, based on the source) using the project's URL from `whoami`, so the user can see their own source arrive without having to ask where to look. A report with a placeholder in it means a step above was skipped, not finished.
+
+## References
+
+- [Host, Docker, Kubernetes, database/queue/cache, and cloud-provider metrics via the OTel Collector](./references/collector/host-and-infra-metrics.md) — receiver configs, IAM/permission caveats, and its own verify loop.

_logfire_sdk/logfire/.agents/skills/logfire-infrastructure/references/collector/host-and-infra-metrics.md

@@ -0,0 +1,229 @@
+# Host & Infrastructure Metrics (OpenTelemetry Collector)
+
+A large share of useful telemetry — host CPU/memory/disk, Kubernetes cluster
+state, and metrics from database/queue/cache servers — comes from
+**infrastructure**, not application code. The OpenTelemetry Collector collects
+these and ships them to Logfire over OTLP, with no changes to your app. Logfire
+is a fully compliant OpenTelemetry backend and ingests OTLP traces, logs, and
+metrics from the Collector — with one metric-type exception: the legacy OTLP
+`Summary` type (superseded by histograms in the OTel spec) is not ingested. If
+a receiver's metrics don't show up and its docs say it emits `Summary` points,
+that's why — look for a histogram- or gauge-producing alternative.
+
+Reach for this path whenever the user wants "as much useful data as would be
+useful," is monitoring a host/VM/cluster, or wants a database/queue/cache server
+watched. App instrumentation alone never produces this data.
+
+> The Collector is optional and is an advanced tool. If the user only wants their
+> app's own traces, the language SDKs (covered in the main skill) are enough.
+
+## Send Collector data to Logfire
+
+Point the Collector's OTLP exporter at the exact Logfire origin selected during
+authentication. The token authenticates the same way as any OTLP client:
+
+```yaml
+exporters:
+  otlphttp/logfire:
+    endpoint: '<selected-logfire-origin>'
+    headers:
+      Authorization: '${env:LOGFIRE_TOKEN}'
+```
+
+Use the project-scoped write token created by the authentication flow's `projects use`
+command. Follow its [credential handoff instructions](https://pydantic.dev/.well-known/agent-skills/logfire-instrumentation/references/auth.md#if-the-calling-skill-needs-a-write-token-not-just-a-cli-session) to place only the token value into a gitignored env file, Kubernetes Secret, or the deployment's existing secret manager without printing it. Set that credential as `LOGFIRE_TOKEN` wherever the Collector runs -- `${env:NAME}` is the Collector's own config-substitution syntax, resolved at startup, never hardcoded into the Collector config. Add the exporter to your metrics (and/or logs/traces) pipelines.
+
+Full setup, topologies, and processors:
+https://pydantic.dev/docs/logfire/guides/otel-collector/otel-collector-overview/
+
+## Host metrics → Hosts page
+
+Use the `hostmetrics` receiver. Each host that ships these metrics appears on the
+**Hosts** page with CPU, memory, load, disk, and network charts.
+
+```yaml
+receivers:
+  hostmetrics:
+    collection_interval: 60s
+    scrapers:
+      cpu:
+        metrics:
+          system.cpu.utilization:
+            enabled: true
+      memory:
+        metrics:
+          system.memory.utilization:
+            enabled: true
+      load:
+      disk:
+      filesystem:
+        include_virtual_filesystems: false
+        metrics:
+          system.filesystem.utilization:
+            enabled: true
+      network:
+      processes:
+processors:
+  resourcedetection:
+    detectors: [env, system]
+    system:
+      hostname_sources: [os]
+service:
+  pipelines:
+    metrics:
+      receivers: [hostmetrics]
+      processors: [resourcedetection]
+      exporters: [otlphttp/logfire]
+```
+
+Set `host.name` (and other host resource attributes) so hosts are identified
+correctly. Guide:
+https://pydantic.dev/docs/logfire/guides/otel-collector/host-monitoring/
+
+**App-only alternative:** if you can't run a Collector but the app process should
+report its host's metrics, call `logfire.instrument_system_metrics()` (Python,
+needs the `system-metrics` extra). The Collector `hostmetrics` receiver is
+preferred for true host coverage because it runs per host, independent of any app.
+
+## Docker containers → Docker page
+
+Use the `docker_stats` receiver — **Contrib-only, not in the core Collector image** (`otelcol-contrib`, not `otelcol`) — pointed at the Docker socket, and added to an active metrics pipeline (a receiver defined but never referenced under `service.pipelines` collects nothing):
+
+```yaml
+receivers:
+  docker_stats:
+    endpoint: unix:///var/run/docker.sock
+    api_version: "1.44"   # quoted string -- a bare float like 1.44 is rejected
+
+service:
+  pipelines:
+    metrics:
+      receivers: [docker_stats]
+      exporters: [otlphttp/logfire]
+```
+
+Modern builds of the receiver auto-negotiate the API version; older builds
+default to 1.25, too old for current Docker/OrbStack, so pin a recent version
+to avoid API-version errors. The collector needs permission to read the socket:
+mount `/var/run/docker.sock` into the container and run it as a user that can
+read it (often `user: "0:0"` in Docker Compose) -- call out that Docker socket
+access, especially as root, is effectively root-level control of the host
+before doing this.
+
+Group containers under the real host by passing the host name in from the
+shell and adding a `resourcedetection` processor with the `env` detector to
+the pipeline — setting `OTEL_RESOURCE_ATTRIBUTES` alone does nothing; nothing
+reads that environment variable into the actual resource attributes without
+it:
+
+```yaml
+# docker-compose.yml
+services:
+  otel-collector:
+    environment:
+      OTEL_RESOURCE_ATTRIBUTES: host.name=${HOST_NAME}
+```
+
+```yaml
+processors:
+  resourcedetection:
+    detectors: [env]
+
+service:
+  pipelines:
+    metrics:
+      receivers: [docker_stats]
+      processors: [resourcedetection]
+      exporters: [otlphttp/logfire]
+```
+
+```bash
+HOST_NAME=$(hostname) docker compose up
+```
+
+A literal `$(hostname)` inside a Compose value does not expand -- it has to
+come in from the shell.
+
+If the collector runs in a container and the Logfire base URL is a
+localhost/LAN address (self-hosted or local dev), reach the host via
+`host.docker.internal` (add `extra_hosts: ["host.docker.internal:host-gateway"]`
+in Compose), not `localhost` -- inside the container, `localhost` is the
+collector itself. A public cloud Logfire URL needs no change.
+
+Guide: https://pydantic.dev/docs/logfire/observe/docker/
+
+## Kubernetes → Kubernetes page
+
+Collect cluster state, per-node/per-pod metrics, and the `k8s.*` resource
+attributes (`k8s.cluster.name`, `k8s.namespace.name`, `k8s.pod.name`,
+`k8s.deployment.name`, ...) that drive the **Kubernetes** page. The recommended
+pattern is two Collectors — a Deployment for cluster-level state
+(`k8sclusterreceiver`) and a DaemonSet for per-node/pod metrics
+(`kubeletstatsreceiver`) — plus the `k8sattributesprocessor` to stamp the same
+`k8s.*` attributes onto traces from your applications.
+
+Guide:
+https://pydantic.dev/docs/logfire/guides/otel-collector/kubernetes-monitoring/
+
+## Database / queue / cache servers → Metrics & Dashboards
+
+The Collector ships receivers for common infrastructure services. Add the
+relevant receiver and its metrics become queryable in the **Metrics** explorer
+and available for **dashboard panels** and **alerts**:
+
+| Service | Receiver | Example metric prefix |
+|---------|----------|-----------------------|
+| PostgreSQL | `postgresql` | `postgresql.*` |
+| MySQL | `mysql` | `mysql.*` |
+| Redis | `redis` | `redis.*` |
+| MongoDB | `mongodb` | `mongodb.*` |
+| Kafka | `kafkametrics` | `kafka.*` |
+| RabbitMQ | `rabbitmq` | `rabbitmq.*` |
+| Nginx | `nginx` | `nginx.*` |
+| Apache HTTP | `apache` | `apache.*` |
+| Elasticsearch | `elasticsearch` | `elasticsearch.*` |
+| Memcached | `memcached` | `memcached.*` |
+
+These receivers live in the OpenTelemetry Collector Contrib distribution. Match
+the receiver to the services the project actually depends on (read
+`pyproject.toml` / `package.json` / `docker-compose.yml` to detect them), and set
+`service.instance.id` on each so per-instance metrics stay distinct.
+
+## Cloud provider metrics → Metrics & Dashboards
+
+- **GCP**: the `googlecloudmonitoring` receiver pulls Cloud Monitoring (formerly
+  Stackdriver) metrics — needs a service account with monitoring read
+  permissions and an explicit `metrics_list` of metric names to collect.
+- **AWS**: the `awsecscontainermetrics` receiver reads ECS task-metadata-endpoint
+  metrics directly, no extra IAM beyond the task role. For broader CloudWatch
+  metrics (RDS, ALB, and other services not on the ECS metadata endpoint), use
+  the `awscloudwatch` receiver available in the stock Contrib distribution.
+  Configure `metrics.queries[].stats` or `metrics.discovery.stats` explicitly
+  (for example, `[Average]`) so the receiver emits Gauge points; omitted stats
+  produce Summary points. Logfire drops those points at ingest and emits a
+  `logfire ingest error`; payloads that mix supported and Summary points may be
+  partially ingested. It needs
+  `cloudwatch:GetMetricData` /
+  `GetMetricStatistics` / `ListMetrics` IAM permissions.
+
+Full setup, IAM policies, and example ECS/Cloud Run deployments:
+https://pydantic.dev/docs/logfire/guides/cloud-metrics/
+
+## Service & resource metadata
+
+Whatever the source, set resource attributes so data is grouped correctly across
+the UI. From the Collector, use the `resource`/`resourcedetection` processors. The
+`OTEL_RESOURCE_ATTRIBUTES` variable is consumed only when the `resourcedetection`
+processor includes its `env` detector:
+
+- `service.name`, `service.version`, `deployment.environment.name`
+- `service.instance.id` — per-replica identity (standard dashboards filter on it)
+- `host.name` — required for the Hosts page to identify a host
+
+## Verify
+
+After wiring a receiver + the Logfire exporter, restart the Collector and check
+that the corresponding page (Hosts / Kubernetes) or the Metrics explorer shows
+the new data within a minute or two. If nothing appears: confirm the exporter
+endpoint/region and write token, that the receiver is in an active pipeline, and
+that resource attributes (`host.name`, `service.name`) are set.