madesroches/micromegas/micromegas-query

The user's query or question: $ARGUMENTS

MANDATORY RULES — read before writing ANY query

1. Every query MUST have `--begin` (and optionally `--end`). No exceptions — not for SELECT DISTINCT, not for process lookups, not for exploratory queries. Default to --begin 1h when in doubt; narrow further when possible. The only exception: --all may be used for lightweight aggregate-only queries (COUNT(*), COUNT(DISTINCT ...), MIN/MAX) that return a single row or a small fixed number of rows. Never use --all with queries that return raw rows or unbounded GROUP BY result sets.
2. Every query MUST have a `LIMIT` clause unless the user explicitly asks for all rows or the query is a pure aggregate (COUNT, SUM, etc.) guaranteed to return a small result set. Default to LIMIT 20. For GROUP BY queries, still add LIMIT (e.g. LIMIT 50).
3. Use `--begin`/`--end` CLI flags for time filtering, never `WHERE time >= ...` in SQL. The CLI flags enable server-side partition pruning, making queries much faster.
4. Use `view_instance()` for single-process/stream queries. Much better performance than filtering with WHERE.
5. `thread_spans` has no global view — must use view_instance('thread_spans', stream_id) or process_spans(process_id, 'thread').
6. `async_events` has no global view — must use view_instance('async_events', process_id) or process_spans(process_id, 'async').

Violating these rules can crash the analytics service by exhausting its memory.

Setup

Before running the user's actual query, verify the environment with two cheap, no-network checks: a CLI-presence check, and a Python config probe. Run both — they test different things, since micromegas-query (a console script, typically on PATH via pipx/poetry/venv) and the micromegas module importable by the ambient python3/python/py -3 interpreter can each be present without the other.

First, check the CLI is on PATH:

micromegas-query --help

Second, use an ordinary shell check (use Bash on Linux/macOS, or on Windows without Git Bash, PowerShell) for the config probe. Try python3 first; if that command is not found, fall back to python, then py -3:

python3 -c "import os; from micromegas.cli.config import resolve_connection; c = resolve_connection(); print(c.uri); print(c.oidc_issuer); print(c.oidc_client_id); print(os.path.exists(c.token_file))"

For a config with no profiles map, this call is total — it never fails just because nothing is configured yet, since a missing config resolves to the default grpc://localhost:50051 — and it never triggers a browser login by itself (see the Interactive SSO note below). The one exception: if ~/.micromegas/config.json has a profiles map but no profile is selected (no default_profile set, and neither --profile nor MICROMEGAS_PROFILE given to this probe), or a stale MICROMEGAS_PROFILE is set against a flat config with no profiles map, this call raises a Python ProfileError instead — see the probe-outcome bullet below for how to handle it. Read the two checks together:

• Only one of the two checks succeeds — this is a PATH/interpreter mismatch, not "not

installed": use whichever one works (the CLI is what actually runs queries, so prefer it, and treat the Python probe as best-effort diagnostics of the resolved config/OIDC state). Only raise it with the user if neither check works after trying pip install/pip install --upgrade below. If instead it's specifically the CLI that's missing while the Python probe succeeds, that means the interpreter's scripts/bin directory isn't on PATH — not a package problem, so don't suggest pip install — tell the user this directly rather than trying to proceed.

• `ModuleNotFoundError: No module named 'micromegas'`, and the CLI is also missing — the

package isn't installed. Run: `` pip install micromegas ``

• Any other import error naming something inside `micromegas` (e.g.

No module named 'micromegas.cli.config') — an older micromegas version is already installed that predates this config module. pip install micromegas alone is a no-op in this case; run: `` pip install --upgrade micromegas ``

• Prints four lines with no error — the package is present and importable. Read the four

printed values (uri, oidc_issuer, oidc_client_id, token-file-exists) as follows:

• A printed uri of grpc://localhost:50051 is ambiguous — it may be a deliberate local

deployment, or nothing may be configured yet. Don't treat it as reason to overwrite an existing config on its own; ask the user first if you're unsure whether it's configured.

• If oidc_issuer and oidc_client_id are both None, no OIDC is configured — no further

setup is implied for auth; either the URI is enough (plain connection) or the user still needs to provide connection details (see below).

• Raises `ProfileError` (an uncaught traceback naming ProfileError, not a clean CLI usage

error, since this probe calls resolve_connection() directly) — treat this as a profile-selection problem, not a broken install. There are three distinct causes; read the message to tell them apart:

• A profiles map exists but no profile is selected — the error message lists the available

profile names. Prefer offering to set default_profile in config.json to one of them: this is the option that keeps the config probe working, since the probe is a fixed command (pinned in this skill's allowed-tools) that always calls resolve_connection() with no arguments and has no way to take a --profile flag itself. If the user instead wants a session-only --profile <name> (passed on every micromegas-query/micromegas-logout call, without touching config.json), be explicit that this leaves the probe permanently raising ProfileError for the rest of the session — token/login state for that profile is then unknown to you. In that case, don't run the first micromegas-query --profile <name> call yourself; ask the user to run it themselves, since you can't tell from the broken probe whether it's safe (see the Interactive SSO note below on why running a possibly-first, possibly-token-less call yourself risks blocking on a browser login.)

• No profiles map exists at all, but MICROMEGAS_PROFILE is set (a stale env var left over

against a flat config) — the error lists no profile names, and setting default_profile does nothing since there's no profiles map for it to select from. Advise the user to unset MICROMEGAS_PROFILE, or, if they actually want named profiles, migrate the flat config into a profiles map.

• The message is unknown profile '<name>' (available: ...) — a profile name was resolved but

isn't in the profiles map. This looks similar to the "no profile selected" case above (both list available profile names), but setting default_profile will not fix it: --profile and MICROMEGAS_PROFILE both take precedence over default_profile, so a typo'd or stale MICROMEGAS_PROFILE env var (or a mistyped --profile flag) would keep overriding it. Check MICROMEGAS_PROFILE and any --profile flag for a typo against the listed available names first, before touching config.json.

If the user hasn't told you where to connect, ask them to provide:

• Their analytics service URI (e.g. https://analytics.example.com:443)
• If their deployment uses OIDC authentication: the issuer URL, client ID, and audience

(Scope is not part of this flow — see the OIDC scope note below.)

If the user instead wants to keep multiple named connections around (e.g. prod/dev/local) and switch between them, mention ~/.micromegas/config.json's profiles map, selected via --profile/MICROMEGAS_PROFILE, as the alternative to the single flat uri/client_id/issuers keys walked through below — same per-profile shape, just nested under profiles.<name> with a default_profile key picking the one used when no flag/env var is given.

Once the user provides the values, read ~/.micromegas/config.json first (it may already have content to preserve). If it already has a profiles map, write the new values into that profile entry — asking the user which profile if none is already active — and set default_profile to that name, rather than merging into the top-level uri/client_id/issuers keys (which are silently ignored once profiles is present, and would otherwise leave the skill writing dead config and then mis-diagnosing the unchanged active profile on the next probe):

{
  "default_profile": "<selected profile name>",
  "profiles": {
    "<selected profile name>": {
      "uri": "<value from user>",
      "client_id": "<value from user, only if OIDC>",
      "issuers": [{ "issuer": "<value from user>", "audience": "<value from user>" }]
    }
  }
}

Otherwise (no profiles map exists yet), merge the new values into the flat top-level shape instead, exactly as before:

{
  "uri": "<value from user>",
  "client_id": "<value from user, only if OIDC>",
  "issuers": [{ "issuer": "<value from user>", "audience": "<value from user>" }]
}

Either way, this takes effect immediately for every subsequent micromegas-query call in this session or any future one — no shell profile edit or new terminal required, since the library reads this file on every invocation.

Legacy env var precedence: MICROMEGAS_ANALYTICS_URI/MICROMEGAS_OIDC_* environment variables always take precedence over config.json (a previous version of this skill instructed setting these in ~/.micromegas_env, sourced from ~/.bashrc/~/.zshrc). If the verification probe below still shows stale values after you've written config.json, check the user's shell profile for a leftover source ~/.micromegas_env line or these env vars set directly, and ask them to remove it.

OIDC scope: there's no config.json field for oidc_scope — it's only read from the MICROMEGAS_OIDC_SCOPE environment variable, with no config-file fallback. The library already defaults it to "openid email profile offline_access" when unset, which covers the common case. If the user needs a non-default scope (e.g. Azure's api://{client_id}/.default), tell them to set MICROMEGAS_OIDC_SCOPE themselves in their own shell profile — that's outside this skill's automated config flow.

Interactive SSO: the setup probe above makes no network calls and can never trigger a login. Only the first real micromegas-query call can, and only when oidc_issuer and oidc_client_id are both configured — connect() takes the OIDC path only when both are truthy. When that's the case, check the probe's token-file-exists output:

• If it's False, no cached token exists yet, so that first micromegas-query call may open a

browser for login and block waiting for the user. Ask the user to run that first call themselves, in their own session, rather than attempting it yourself and hanging.

• If it's True, a cached token already exists and load_or_login() will try it before ever

considering a browser — go ahead and run the query yourself. If that token has expired or been revoked, this does not hang: the query fails cleanly with an error like Token refresh failed: ... Please re-authenticate. If you see that error, clear the stale token: if a profiles map is in use, run micromegas-logout --profile <active profile> to narrow the clear to that one profile — a bare micromegas-logout wipes every profile's cached token, not just the stale one. Otherwise (flat config, no profiles map), run bare micromegas-logout. Either way, then ask the user to re-run the query themselves in their own session (this will trigger a fresh interactive login).