openobserve-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{openobserve_cli-0.1.0 → openobserve_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openobserve-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: CLI for the OpenObserve HTTP API
 Project-URL: Homepage, https://github.com/paveldedik/oo-cli
 Project-URL: Repository, https://github.com/paveldedik/oo-cli
@@ -111,6 +111,24 @@ oo spec refresh          # refetch after an OpenObserve upgrade
 Without a reachable spec the CLI falls back to v1, except for `alerts`, `folders` and
 `reports`, the three resources that have a v2 in OpenObserve 0.91.
 
+## Skill for agents
+
+The CLI carries a skill for coding agents: how the commands map onto the API, what the
+bodies look like, and a reference for every endpoint, written from an instance's own
+OpenAPI document. It installs itself.
+
+```bash
+oo skill install            # -> ~/.claude/skills/openobserve
+oo skill update             # after upgrading the CLI
+```
+
+`--dir` puts it somewhere else (`oo skill install --dir .claude/skills` for one project),
+`--force` overwrites an existing copy, and `oo skill path` prints the bundled original.
+Without installing anything: `uvx openobserve-cli skill install`.
+
+The files are also plain Markdown in `skills/openobserve`, so any agent that reads
+Markdown can be pointed straight at `SKILL.md`.
+
 ## Development
 
 ```bash

{openobserve_cli-0.1.0 → openobserve_cli-0.2.0}/README.md

@@ -88,6 +88,24 @@ oo spec refresh          # refetch after an OpenObserve upgrade
 Without a reachable spec the CLI falls back to v1, except for `alerts`, `folders` and
 `reports`, the three resources that have a v2 in OpenObserve 0.91.
 
+## Skill for agents
+
+The CLI carries a skill for coding agents: how the commands map onto the API, what the
+bodies look like, and a reference for every endpoint, written from an instance's own
+OpenAPI document. It installs itself.
+
+```bash
+oo skill install            # -> ~/.claude/skills/openobserve
+oo skill update             # after upgrading the CLI
+```
+
+`--dir` puts it somewhere else (`oo skill install --dir .claude/skills` for one project),
+`--force` overwrites an existing copy, and `oo skill path` prints the bundled original.
+Without installing anything: `uvx openobserve-cli skill install`.
+
+The files are also plain Markdown in `skills/openobserve`, so any agent that reads
+Markdown can be pointed straight at `SKILL.md`.
+
 ## Development
 
 ```bash

{openobserve_cli-0.1.0 → openobserve_cli-0.2.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 # "oo", "oo-cli" and "openobserve" are all taken on PyPI.
 name = "openobserve-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "CLI for the OpenObserve HTTP API"
 readme = "README.md"
 keywords = ["openobserve", "observability", "logs", "metrics", "traces", "cli"]
@@ -42,6 +42,14 @@ dev = ["pytest>=8", "mypy>=1.18", "ruff>=0.14"]
 [tool.hatch.build.targets.wheel]
 packages = ["src/oo_cli"]
 
+# The agent skill lives at the top of the repository, where agents browsing GitHub find
+# it, and rides along in the package so `oo skill install` needs no checkout.
+[tool.hatch.build.targets.wheel.force-include]
+"skills/openobserve" = "oo_cli/_skill"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "skills", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
 [tool.ruff]
 line-length = 100
 target-version = "py311"

openobserve_cli-0.2.0/skills/openobserve/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: openobserve
+description: Query and manage OpenObserve from a terminal with the `oo` CLI - search logs, traces and metrics with SQL or PromQL, and read or change streams, dashboards, alerts, pipelines, functions and reports. Use for any task that mentions OpenObserve, an `oo` command, or an OpenObserve API path.
+license: MIT
+---
+
+# OpenObserve from the command line
+
+`oo` is a transcription of the OpenObserve HTTP API, not a model of it. One rule covers
+almost everything:
+
+```
+oo <method> <resource>   ->   <METHOD> /api/{org}/<resource>
+```
+
+So `oo get dashboards` is `GET /api/default/dashboards`, and `oo delete alerts/7` is
+`DELETE /api/v2/default/alerts/7`. Where an endpoint exists in two versions the CLI picks
+v2; there is no version flag. Anything the rule does not reach is still one command away
+with `oo api <METHOD> <path>`.
+
+Install with `uv tool install openobserve-cli`, or run it without installing:
+`uvx openobserve-cli get streams`. This skill came from that package - `oo skill update`
+refreshes it after the CLI is upgraded.
+
+## Start here
+
+Check what you are pointed at before anything else - it is the difference between an empty
+result and an empty instance:
+
+```bash
+oo api GET /healthz          # {"status":"ok"} - confirms it is an OpenObserve
+oo get organizations         # confirms the credentials and lists the orgs you can use
+oo get streams               # what data this org actually holds
+```
+
+Configuration is environment only:
+
+| Variable                  | Required                          | Default                 |
+|---------------------------|-----------------------------------|-------------------------|
+| `OO_ENDPOINT`             | optional                          | `http://localhost:5080` |
+| `OO_ORG`                  | optional                          | `default`               |
+| `OO_TOKEN`                | to reach anything but `/healthz`  | -                       |
+| `OO_USER` / `OO_PASSWORD` | instead of `OO_TOKEN`             | -                       |
+| `OO_COOKIE`               | when a gateway guards the host    | -                       |
+| `OO_TIMEOUT`              | optional                          | `60` (seconds)          |
+
+`--endpoint`, `--org` and `--timeout` override the variables per command. Never print a
+token or cookie value back to the user; keep it in the environment.
+
+## The grammar
+
+```bash
+oo get alerts --folder default        # unknown --flags become query parameters
+oo get streams/app_logs/schema        # slashes are path segments
+oo post alerts -f alert.json          # -f file, -d '<literal>', -d @file, -d @-
+oo put alerts/7 -d @- < alert.json    # body on stdin
+oo --org other get streams            # global flags go before the verb
+oo search --sql "select * from k8s_logs limit 10" --from -15m
+oo api GET /api/default/prometheus/api/v1/query --query "up"
+oo spec paths alerts                  # what this instance actually serves
+```
+
+- Output is pretty-printed JSON on stdout; errors on stderr. Pipe into `jq`.
+- Exit code 1 on HTTP >= 400 (the response body is printed), 2 on a bad command.
+- `--raw` prints the body unformatted, for CSV or a large export.
+- Values starting with `-` need `--flag=value`; `--from` and `--to` are handled for you.
+
+## Time
+
+Every timestamp the API takes or returns is **epoch microseconds**. `oo search --from/--to`
+and nothing else accepts friendly forms: `now`, an offset (`-15m`, `-2h`, `-7d`), an epoch
+in seconds/milliseconds/microseconds, or ISO 8601 (local time when it carries no zone).
+Elsewhere - `start_time` in a body, `_values`, alert history - pass microseconds:
+
+```bash
+python3 -c 'import time; print(int(time.time()*1_000_000))'
+date -v-1H +%s000000        # macOS       (GNU: date -d '1 hour ago' +%s000000)
+```
+
+## Searching
+
+`oo search` is the one command that is not a straight transcription: it wraps
+`POST /api/{org}/_search` so the body does not have to be written by hand.
+
+```bash
+oo search --sql "select * from k8s_logs where level = 'error'" --from -1h --size 50
+oo search --sql "select k8s_namespace_name, count(*) as n from k8s_logs
+                 group by k8s_namespace_name order by n desc" --from -6h
+oo search --type metrics --sql "select * from up" --from -5m
+```
+
+`--from` defaults to `-1h`, `--to` to `now`, `--size` to 100, `--type` to `logs`. The SQL is
+DataFusion SQL: the stream is the table, `_timestamp` is microseconds, and full text lives in
+`match_all('needle')`. Read `references/search.md` before writing anything more involved -
+histograms, `_values`, `_around`, async search jobs and the raw `_search` body are all there.
+
+Two habits that keep a search cheap on a busy instance: always bound the time range, and
+aggregate in SQL rather than pulling rows and counting them locally. A wide range over a raw
+stream can cost the instance far more memory than it costs you to type.
+
+## Common tasks
+
+| Question | Command |
+|----------|---------|
+| what is in this instance | `oo get streams`, then `oo get streams/<name>/schema` |
+| errors in the last hour | `oo search --sql "select * from <stream> where level = 'error'" --from -1h` |
+| how many, by service | `oo search --sql "select service, count(*) as n from <stream> group by service order by n desc" --from -6h` |
+| which values does this field take | `oo get <stream>/_values --fields <field> --size 20 --start_time <us> --end_time <us>` |
+| current value of a metric | `oo api GET /api/{org}/prometheus/api/v1/query --query '<promql>'` |
+| which alerts exist, and are they on | `oo get alerts \| jq -r '.list[] \| "\(.enabled) \(.name)"'` |
+| why an alert did not fire | `oo get alerts/history --alert_id <id> --start_time <us> --end_time <us>` |
+| back up a dashboard | `oo get dashboards/<id> --folder <folder> > dashboard.json` |
+| change one field of an object | read it, edit the JSON, `oo put <resource>/<id> -f patched.json` |
+| does this instance have X | `oo spec paths <needle>` |
+
+## Rules worth keeping
+
+1. **Read before you write.** `PUT` replaces the whole object. Fetch it, edit that JSON,
+   send it back - never hand-write a replacement from the docs.
+2. **Dashboards need their `hash`.** `PUT dashboards/<id>` takes `?folder=<id>&hash=<hash>`
+   from the object you just read; without it a concurrent edit is silently overwritten.
+3. **Folders are ids, not names.** `--folder default` is the id of the default folder;
+   any other folder is a ksuid you get from `oo get folders/<dashboards|alerts|reports>`.
+4. **Deletes are permanent** and `oo delete streams/<name> --delete_all=true` takes the
+   alerts and dashboards with it. Confirm with the user before any delete.
+5. **Ask the spec, not your memory.** `oo spec paths <needle>` lists what the connected
+   instance serves; `oo spec refresh` refetches it after an upgrade. Endpoint availability
+   differs between OSS and enterprise builds - several alert and cipher endpoints answer
+   "not supported" on OSS.
+6. When a command says a path *is not in the spec*, the resource name is probably wrong -
+   check with `oo spec paths` instead of retrying variations.
+
+## References
+
+| File | What is in it |
+|------|---------------|
+| `references/cli.md` | Full command grammar, v1/v2 resolution, the spec cache, gateways, error messages |
+| `references/search.md` | `_search` body, SQL dialect, histograms, `_values`, `_around`, search jobs, patterns |
+| `references/metrics.md` | PromQL instant/range queries, labels, series, metadata, metric ingestion |
+| `references/alerts.md` | Alert model (v2), trigger and query conditions, destinations, templates, history, incidents |
+| `references/dashboards.md` | Dashboards, panels, annotations, folders, scheduled reports |
+| `references/streams.md` | Streams, schemas, settings, retention, ingestion endpoints, enrichment tables |
+| `references/pipelines.md` | Pipelines (nodes and edges), VRL functions, actions |
+| `references/admin.md` | Organizations, settings, users, roles, groups, service accounts, tokens, KV |
+| `references/endpoints.md` | Every endpoint the API exposes, as the `oo` command that reaches it |

openobserve_cli-0.2.0/skills/openobserve/references/admin.md

@@ -0,0 +1,126 @@
+# Organizations, users and the rest
+
+## Organizations
+
+```bash
+oo get organizations                 # /api/organizations - no org in the path
+oo post organizations -d '{"name":"team-b"}'
+oo put rename -d '{"new_name":"Platform"}'
+oo get summary                       # ingestion, storage, stream and function counts
+```
+
+`oo get organizations` is the first call to make against an unfamiliar instance: it proves
+the credential works and lists the org identifiers `--org` accepts. A root user sees every
+organization. `oo get clusters` lists clusters in a distributed deployment.
+
+## Ingestion tokens
+
+```bash
+oo get passcode        # the current ingestion token for this user and org
+oo put passcode        # rotate it - every ingester using the old one breaks
+oo get rumtoken
+oo post rumtoken       # create the first RUM token
+oo put rumtoken        # rotate it
+```
+
+These return credentials. Never print one into a chat, a commit or a log; redirect to a file
+or into an environment variable.
+
+## Settings
+
+```bash
+oo get settings
+oo post settings -d '{"scrape_interval": 15}'
+```
+
+Org settings hold `scrape_interval`, `trace_id_field_name` / `span_id_field_name`,
+`max_series_per_query`, `min_auto_refresh_interval`, `toggle_ingestion_logs`,
+`usage_stream_enabled`, `enable_streaming_search`, `streaming_aggregation_enabled`, the two
+theme colours and `cross_links`.
+
+A newer key-value system sits alongside it, resolving system -> org -> user:
+
+```bash
+oo get settings/v2                         # everything, resolved
+oo get settings/v2 --category ui
+oo get settings/v2/<key> --user_id <id>    # the value this user actually sees
+oo post settings/v2 -d '{"setting_key":"...","setting_value":...,"setting_category":"ui"}'
+oo post settings/v2/user/<user_id> -d '{"setting_key":"...","setting_value":...}'
+oo delete settings/v2/<key>                # falls back to the system default
+```
+
+## Users, roles, groups, service accounts
+
+```bash
+oo get users
+oo post users -d '{"email":"a@example.com","password":"...","role":"admin","first_name":"A","last_name":"B"}'
+oo put users/<email> -d '{"first_name":"A"}'
+oo post users/<email> -d '{"role":"member"}'      # add an existing user to this org
+oo delete users/<email>                           # removes from the org
+
+oo get roles                                      # enterprise RBAC
+oo get roles/<role_id>/permissions/<resource>
+oo get roles/<role_id>/users
+oo post roles -d '{"role":"readonly"}'
+oo put roles/<role_id> -f permissions.json
+
+oo get groups
+oo post groups -d '{"name":"platform"}'
+oo put groups/<group_name> -d '{"add_users":["a@example.com"],"add_roles":["readonly"]}'
+```
+
+A service account is a user without a password, used for automation; its token comes from
+`passcode` once the account exists.
+
+```bash
+oo get service_accounts
+oo post service_accounts -d '{"email":"ci@example.com","first_name":"CI","last_name":"bot"}'
+oo delete service_accounts/<email>
+```
+
+Roles and groups are enterprise features and answer with an error on OSS builds. Creating or
+deleting users changes who can reach the data - always confirm first.
+
+## Key-value store
+
+A small per-org store the UI uses and you can too:
+
+```bash
+oo get kv                       # every key
+oo get kv --prefix dashboard_
+oo get kv/<key>                 # the raw value, not JSON
+oo post kv/<key> -d 'some text'
+oo delete kv/<key>
+```
+
+## Short URLs
+
+```bash
+oo post short -d '{"original_url":"https://openobserve.example.com/web/logs?..."}'
+oo api GET /short/default/short/<short_id> --type ui     # resolve without redirecting
+```
+
+## Cipher keys and rate limits
+
+`cipher_keys` (encryption key management) and `ratelimit` (per-module and per-role request
+limits) are enterprise-only:
+
+```bash
+oo get cipher_keys
+oo get ratelimit/module_list --org_id default
+oo get ratelimit/role_list --org_id default --user_role admin
+```
+
+## Health and the spec
+
+```bash
+oo api GET /healthz            # {"status":"ok"}, the one endpoint needing no credential
+oo spec paths                  # every path this build serves
+oo spec refresh                # after an upgrade
+```
+
+## MCP
+
+Recent builds expose `POST /api/{org}/mcp`, an MCP server over the same API. The endpoint
+carries per-operation hints (which operations are exposed, which need confirmation) that this
+skill's guidance is drawn from. Check `oo spec paths mcp` before assuming it is there.

openobserve_cli-0.2.0/skills/openobserve/references/alerts.md

@@ -0,0 +1,184 @@
+# Alerts, destinations and templates
+
+Three objects, in the order you need them:
+
+1. a **template** formats the message,
+2. a **destination** says where it goes and which template it uses,
+3. an **alert** says what to watch and names its destinations.
+
+Alerts live in folders and use the v2 API, so `oo get alerts` is
+`GET /api/v2/{org}/alerts`. Destinations and templates are v1.
+
+## Listing
+
+```bash
+oo get alerts                                  # every alert in the org
+oo get alerts --folder default --enabled true
+oo get alerts --alert_name_substring celery --alert_type scheduled
+oo get alerts --stream_type logs --stream_name k8s_logs
+oo get alerts --page_size 50 --page_idx 1
+```
+
+Filters: `folder` (a folder **id**), `stream_type`, `stream_name` (only with
+`stream_type`), `alert_name_substring` (case-insensitive), `owner`, `enabled`,
+`alert_type` (`all`, `scheduled`, `realtime`, `anomaly_detection`), `page_size`, `page_idx`.
+
+Each item carries `alert_id`, `name`, `enabled`, `folder_id`, `folder_name`,
+`is_real_time`, `last_triggered_at` and `last_satisfied_at`.
+
+```bash
+oo get alerts | jq -r '.list[] | select(.enabled) | "\(.folder_name)/\(.name)"'
+```
+
+## One alert
+
+```bash
+oo get alerts/<alert_id>                       # add --folder <id> for a non-default folder
+oo post alerts/<alert_id>/export                # the same thing, shaped for re-import
+oo patch alerts/<alert_id>/enable --value=false
+oo patch alerts/<alert_id>/trigger              # fire it now, to test the destination
+oo post alerts/<alert_id>/clone -d '{"name": "copy_of_x", "folder_id": "<id>"}'
+oo patch alerts/move -d '{"alert_ids": ["<id>"], "dst_folder_id": "<id>"}'
+oo delete alerts/<alert_id>                     # permanent
+```
+
+## The alert object
+
+Names must be snake_case: no spaces and none of `: # ? & % /` or quotes. `destinations` is
+required and every name in it must already exist.
+
+```json
+{
+  "name": "api_error_rate",
+  "stream_type": "logs",
+  "stream_name": "k8s_logs",
+  "is_real_time": false,
+  "enabled": true,
+  "description": "5xx from the API gateway",
+  "destinations": ["slack_alerts"],
+  "query_condition": {
+    "type": "sql",
+    "sql": "select count(*) as n from k8s_logs where status >= 500"
+  },
+  "trigger_condition": {
+    "period": 10, "frequency": 600, "operator": ">=", "threshold": 5, "silence": 30
+  },
+  "context_attributes": {"team": "platform"},
+  "row_template": "{alert_name} fired: {n}"
+}
+```
+
+### `trigger_condition` - when it runs and what counts as firing
+
+| Field | Unit | Meaning |
+|-------|------|---------|
+| `period` | minutes | how far back each evaluation looks |
+| `frequency` | seconds | how often it evaluates (`frequency_type: "minutes"`) |
+| `frequency_type` | - | `minutes` or `cron` |
+| `cron` | - | schedule when `frequency_type` is `cron` |
+| `timezone` | - | timezone for the cron expression |
+| `operator` | - | `=`, `!=`, `>`, `>=`, `<`, `<=`, `contains`, `not_contains` |
+| `threshold` | - | compared against the row count or the aggregate |
+| `silence` | minutes | mute after firing, so one incident is one notification |
+| `align_time` | - | snap evaluations to the clock |
+| `tolerance_in_secs` | seconds | slack for late-arriving data |
+
+`period` shorter than the data's ingestion delay is the usual reason an alert never fires.
+
+### `query_condition` - what it asks
+
+`type` is one of three, and the other fields follow from it:
+
+- **`custom`** - `conditions` (a condition group), optional `aggregation`, `vrl_function`,
+  `multi_time_range`. The UI builds this one.
+- **`sql`** - `sql` plus optional `vrl_function`. The query must return rows only when
+  something is wrong, or return a number that `trigger_condition` compares.
+- **`promql`** - `promql` plus `promql_condition` (`{"column", "operator", "value"}`), for
+  alerts on metrics.
+
+`aggregation` narrows a custom alert: `function` is one of `avg`, `min`, `max`, `sum`,
+`count`, `median`, `p50`, `p75`, `p90`, `p95`, `p99`, with `group_by` and a `having` clause
+shaped `{"column", "operator", "value", "ignore_case"}`.
+
+`POST /api/v2/{org}/alerts/generate_sql` turns a custom condition into the SQL it would run -
+useful for checking an alert before saving it.
+
+The `conditions` group is the same nested format pipelines use (see `pipelines.md`):
+`{"filterType": "group", "logicalOperator": "AND", "conditions": [...]}` with leaves
+`{"filterType": "condition", "column", "operator", "value", "logicalOperator"}`. When in
+doubt, build one alert in the UI, `oo get alerts/<id>`, and copy the shape.
+
+### Editing an existing alert
+
+```bash
+oo get alerts/<id> > alert.json
+jq '.trigger_condition.threshold = 10' alert.json > patched.json
+oo put alerts/<id> -f patched.json
+```
+
+`PUT` replaces the object, so always start from the current one.
+
+## Destinations
+
+```bash
+oo get alerts/destinations
+oo get alerts/destinations --module pipeline     # pipeline destinations instead
+oo get alerts/destinations/<name>
+oo post alerts/destinations -d '{"name":"slack_alerts","type":"http","url":"https://hooks.example.com/x","method":"post","template":"Default"}'
+oo post alerts/destinations -d '{"name":"oncall_mail","type":"email","emails":["oncall@example.com"],"template":"Default"}'
+oo delete alerts/destinations/<name>
+```
+
+`template` is **required** for an alert destination - without it the destination is created
+as a pipeline destination and no alert can use it. `type` is `http`, `email` or `sns`
+(`sns_topic_arn` + `aws_region`). `headers` adds HTTP headers, `skip_tls_verify` disables
+certificate checks. A destination in use cannot be deleted.
+
+## Templates
+
+```bash
+oo get alerts/templates
+oo get alerts/templates/system/prebuilt      # read-only, Slack/Teams/PagerDuty/...
+oo get alerts/templates/<name>
+oo post alerts/templates -d '{"name":"short","type":"http","body":"{\"text\":\"{alert_name} fired\"}"}'
+```
+
+`body` is the message with `{variable}` placeholders; `title` is used for email. Variables
+come from the alert (`alert_name`, `stream_name`, `org_name`, `alert_start_time`, ...),
+its `context_attributes`, and the matching rows via `row_template`. Templates named
+`system_*` are prebuilt and read-only.
+
+## History and incidents
+
+```bash
+oo get alerts/history --alert_id <id> --start_time <us> --end_time <us> --size 100
+oo get alerts/history --sort_by timestamp --sort_order desc
+```
+
+History comes from the org's own triggers stream: when an alert ran, whether it was
+satisfied, whether it was silenced, how long the evaluation took, and any error. It is the
+first place to look when someone says an alert did not fire.
+
+Incidents group notifications for alerts with `creates_incident: true`:
+
+```bash
+oo get alerts/incidents --status open --limit 20   # open, acknowledged or resolved
+oo get alerts/incidents/stats
+oo get alerts/incidents/<incident_id>
+oo patch alerts/incidents/<incident_id>/update -d '{"status":"resolved"}'  # one field per call
+```
+
+Deduplication (`alerts/deduplication/...`) and RCA are enterprise features; on OSS they
+answer "not supported".
+
+## Folders
+
+```bash
+oo get folders/alerts                        # folder_type is dashboards, alerts or reports
+oo get folders/alerts/name/<folder_name>
+oo post folders/alerts -d '{"name":"platform","description":"team alerts"}'
+oo delete folders/alerts/<folder_id>
+```
+
+`--folder` everywhere takes the **folderId**, not the name. The default folder's id is
+literally `default`.