# Grafana on boxd

> Open and composable observability platform for metrics, logs, and traces.

- Page: https://boxd.sh/integrations/grafana/
- CLI: `run grafana` (11 commands, 7 marked common)
- SDK: `import { grafana } from "@boxd/run"`; every parameter and response type is at `@boxd/run/grafana`
- Triggers: none
- Connect: `run auth grafana` (API key), or https://app.boxd.sh/integrations/detail/grafana
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth grafana      # once: prints a link to connect your account
run grafana           # list its commands
run grafana get-health
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { every, grafana } from "@boxd/run";

every("1 hour", async () => {
  const result = await grafana.getHealth();
  console.log(result);
});
```

Run it with `run grafana.run.ts`. Grafana has no triggers; `every()` polls on a schedule, keeps the script running as a job, and wakes the machine when it is due.

## Commands

Required flags are listed; `run grafana <command> --help` lists the optional ones. "common" marks what `run grafana` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `create-otlp-v1-logs` | `grafana.createOtlpV1Logs()` | `--resourceLogs` | 0 | Create OTLP v1 logs in Grafana Loki |
| `get-distributor-ha-tracker` | `grafana.getDistributorHaTracker()` | — | 0 | Retrieve distributor HA tracker status |
| `get-health` ·common | `grafana.getHealth()` | — | 0 | Check Grafana server health and database connectivity |
| `get-index-gateway-ring` ·common | `grafana.getIndexGatewayRing()` | — | 0 | Retrieve the index gateway hash ring status from Grafana Loki |
| `get-overrides-exporter-ring` | `grafana.getOverridesExporterRing()` | — | 0 | Retrieve the overrides-exporter hash ring status as an HTML page |
| `get-ruler-ring` ·common | `grafana.getRulerRing()` | — | 0 | Retrieve the ruler ring status from Grafana Mimir |
| `get-status` ·common | `grafana.getStatus()` | — | 0 | Check if a valid Grafana Enterprise license is available |
| `get-store-gateway-tenants` | `grafana.getStoreGatewayTenants()` | — | 0 | Retrieves store gateway tenants |
| `post-acs` ·common | `grafana.postAcs()` | `--saml-response` | 1 | Perform SAML Assertion Consumer Service (ACS) operation |
| `query-public-dashboard` ·common | `grafana.queryPublicDashboard()` | `--access-token` `--from` `--panel-id` `--to` | 3 | Query a panel on a public Grafana dashboard to retrieve time-series data and metrics |
| `retrieve-jwks` ·common | `grafana.retrieveJwks()` | — | 0 | Retrieve JSON Web Key Set (JWKS) with all public keys for token verification |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.