sentry-observability（哨兵可观测性）

Sentry — OpenClaw Observability

See what your OpenClaw instance is doing: errors, structured logs, and performance traces — all in Sentry.

Two halves: setup (get telemetry flowing) and investigation (query it with the CLI).

Setup

1. Authenticate

sentry auth login

OAuth device flow — follow the browser prompt. Credentials stored in ~/.sentry/cli.db.

Alternatives (one-liners):

• sentry auth login --token <TOKEN> — paste an auth token directly
• SENTRY_AUTH_TOKEN=<token> — env var, useful in CI

2. Create a Project

Create a dedicated Sentry project for your OpenClaw instance:

sentry api /teams/<org>/<team>/projects/ \
  --method POST \
  --field name="my-openclaw" \
  --field platform=node

Don't know your org/team slugs? List them:

sentry api /organizations/                          # list orgs
sentry api /organizations/<org>/teams/              # list teams in org

3. Get the DSN

sentry project view <org>/my-openclaw --json | jq -r '.dsn'

Or via the keys endpoint:

sentry api /projects/<org>/my-openclaw/keys/ | jq '.[0].dsn.public'

4. Configure OpenClaw

Add the DSN to your openclaw.json:

{
  "plugins": {
    "entries": {
      "sentry": {
        "enabled": true,
        "config": {
          "dsn": "https://examplePublicKey@o0.ingest.sentry.io/0",
          "enableLogs": true
        }
      }
    }
  }
}

Note: Config goes under plugins.entries.sentry.config, not directly under sentry.

Then install the Sentry plugin. See references/plugin-setup.md for the full plugin implementation using @sentry/node.

Log buffer gotcha: Sentry's structured logs buffer up to 100 items before auto-flushing. For low-volume services like OpenClaw, logs may sit in the buffer for a long time. The plugin should call _INTERNAL_flushLogsBuffer(client) periodically (e.g. every 30s) and before Sentry.flush() on shutdown. See references/plugin-setup.md for the implementation.

5. Verify

Restart your OpenClaw gateway, then check Sentry for incoming events:

sentry issue list <org>/my-openclaw --limit 5

Investigation

Once telemetry is flowing, use the CLI to query your OpenClaw's errors, traces, and events.

List Issues

sentry issue list <org>/<project>
sentry issue list <org>/<project> --query "is:unresolved" --sort freq --limit 20
sentry issue list <org>/                              # all projects in org

View an Issue

sentry issue view <short-id>                          # e.g. MY-OPENCLAW-42
sentry issue view <short-id> --json                   # structured output

AI Root Cause Analysis

sentry issue explain <issue-id>                       # Seer analyzes the root cause
sentry issue explain <issue-id> --force               # force fresh analysis
sentry issue plan <issue-id>                          # generate a fix plan (run explain first)

Structured Logs

sentry log list <org>/<project>                       # last 100 logs
sentry log list <org>/<project> --limit 50            # last 50
sentry log list <org>/<project> -q 'level:error'      # filter by level
sentry log list <org>/<project> -q 'database'         # filter by message
sentry log list <org>/<project> -f                    # stream in real-time (2s poll)
sentry log list <org>/<project> -f 5                  # stream with 5s poll
sentry log list <org>/<project> --json                # structured output

View a specific log entry:

sentry log view <log-id>                              # 32-char hex ID
sentry log view <log-id> --json
sentry log view <log-id> --web                        # open in browser

Inspect Events

sentry event view <event-id>                          # full stack trace + context
sentry event view <event-id> --json

Direct API Calls

sentry api /projects/<org>/<project>/issues/ --paginate
sentry api /issues/<id>/ --method PUT --field status=resolved
sentry api /issues/<id>/ --method PUT --field assignedTo="user@example.com"

Workflow: Investigate an Error

1. sentry issue list <org>/<project> --query "is:unresolved" --sort date --limit 5
2. sentry issue view <short-id> — context, affected users, timeline
3. sentry issue explain <issue-id> — AI root cause analysis
4. sentry issue plan <issue-id> — concrete fix steps
5. Fix → sentry api /issues/<id>/ --method PUT --field status=resolved

Reference

• Full CLI commands: references/cli-commands.md
• Plugin implementation: references/plugin-setup.md
• CLI docs: https://cli.sentry.dev
• Sentry API: https://docs.sentry.io/api/
• Node SDK: https://docs.sentry.io/platforms/javascript/guides/node/