ojiichan 0.5.0

Pseekoo diagnostics toolkit for ELK, Rustrak/Sentry/Bugsink, Scaleway Cockpit logs, and issue handoff workflows.

ojiichan

Pseekoo diagnostics toolkit for projects that report to ELK, Bugsink/Sentry/Rustrak, and Scaleway Cockpit.

It provides both:

• a Python library (ojiichan) for structured ELK events and Sentry/Bugsink setup;
• a CLI (ojiichan) for health checks, recent logs, and test event emission.

It standardizes the same observability workflow across Python services — and reads platform runtime logs (Scaleway Serverless Functions stdout/stderr) alongside application events, so one tool covers app-level and infra-level diagnostics.

Sibling services in other languages can't import the Python library, so ojiichan also scaffolds env-driven TypeScript and Rust equivalents (ojiichan scaffold --lang typescript|rust) that report to the same ELK + Rustrak/Sentry stack.

Install

uv add ojiichan
# with Locke/Vaultwarden credential support:
uv add "ojiichan[vault]"
# or for development:
uv sync

Configuration and credentials

Ojiichan resolves explicit environment variables first, then Locke/Vaultwarden secrets when installed with the vault extra. The checked-in locke.json documents the expected Vaultwarden paths; no sample env file with secret-shaped values is needed.

Default vault folder: ojiichan. Override it with OJIICHAN_VAULT_FOLDER when needed.

Non-secret options can still be set as env vars, for example ELASTICSEARCH_PORT, ELASTICSEARCH_USE_SSL, ELASTICSEARCH_VERIFY_CERTS, ELASTICSEARCH_TIMEOUT, and BUGSINK_TIMEOUT.

CLI

ojiichan health --hours 6
ojiichan logs --hours 2 --topic matrix --failures-only
ojiichan emit matrix_exchange_failed --topic auth --level error --failure \
  --data '{"operation":"matrix_exchange","room_id":"!abc"}'
ojiichan resolve-issue 7b3a... --backend rustrak --project-id 42
ojiichan resolve-issue 98765 --backend sentry

# Scaffold observability setup for a TypeScript or Rust service
ojiichan scaffold --lang typescript --backend rustrak --dir ../m3rp-api
ojiichan scaffold --lang rust --dir ../some-rust-service

# Scaleway Cockpit (Loki) runtime logs — e.g. a Serverless Function's stdout/stderr
ojiichan logs --backend scaleway --hours 2 --failures-only
ojiichan logs --backend scaleway --source m3rp-api-staging-api --topic "Login failed"

Scaleway Cockpit logs

--backend scaleway reads logs from a project's Scaleway Cockpit via the Loki HTTP API. --source maps to the Loki resource_name label (a function name); --topic is a substring line filter; --failures-only keeps error/exception/5xx lines. When configured, ojiichan health also reports a Scaleway section.

One-time setup (store the two secrets in the vault under ojiichan/scaleway/…, or export OJIICHAN_SCALEWAY_LOKI_URL / OJIICHAN_SCALEWAY_COCKPIT_TOKEN):

scw cockpit data-source list region=fr-par          # copy the type=logs "url"
scw cockpit token create name=ojiichan region=fr-par token-scopes.query_logs=true

Scaffolding TypeScript / Rust services

ojiichan's Python library can't run inside a Node or Rust service, so ojiichan scaffold writes env-driven equivalents that report to the same backends — Sentry/Rustrak error reporting plus ELK structured events.

ojiichan scaffold --lang typescript --backend rustrak --dir ./service
ojiichan scaffold --lang rust --dir ./service          # add --force to overwrite

Generated files (existing files are skipped unless --force):

• TypeScript — src/lib/config.ts (env resolution), src/lib/sentry.ts (initSentry / captureException / flushSentry), src/lib/elk.ts (logEvent), src/handler-scaleway.ts (a withObservability wrapper that flushes before a Serverless Function freezes), and OBSERVABILITY.md.
• Rust — src/observability.rs (init_sentry / capture_error / log_event) and OBSERVABILITY.md.

Every value is read from the environment, preferring an OJIICHAN_-prefixed override then the conventional name (SENTRY_DSN, ELASTICSEARCH_HOST, …), so the scaffolded service shares the Python toolkit's resolution order. The generated OBSERVABILITY.md lists the required packages (@sentry/node; sentry + reqwest crates) and wiring steps. The --backend flag only adjusts the documentation references — the SDK wiring is identical because Rustrak is Sentry-compatible.

ojiichan: key=value diagnostic annotations (below) are recognized in //, ///, //!, and /* … */ comments too, so the hints work in TypeScript and Rust source.

Library

from ojiichan import ElkClient, init_sentry

init_sentry(service="stoz3n-chat-agent", environment="development")

elk = ElkClient(service="stoz3n-chat-agent")
elk.log_event(
    "matrix_exchange_start",
    {"operation": "matrix_exchange", "user_id": "@user:example.org"},
    topic="auth",
)

For exception paths:

try:
    ...
except Exception as exc:
    elk.log_event(
        "matrix_exchange_failed",
        {"operation": "matrix_exchange", "error": str(exc)},
        level="error",
        topic="auth",
        failure=True,
    )
    raise

Issue resolution

Ojiichan resolves issues through Rustrak or Sentry. Bugsink is supported for ingestion and issue reads but does not support resolution from ojiichan; calling resolve_issue on Bugsink returns a friendly "not supported" message that points users at Rustrak/Sentry instead.

from ojiichan import RustrakClient, SentryApiClient

RustrakClient().resolve_issue("7b3a-…-uuid", project_id=42)
SentryApiClient().resolve_issue("98765")

Projects pick their default backend by exporting OJIICHAN_ISSUE_BACKEND (rustrak, sentry, or bugsink). The CLI/--backend auto honors that choice; with no preference it prefers Rustrak then falls back to Sentry.

Credentials:

• Rustrak: RUSTRAK_API_TOKEN; optionally RUSTRAK_BASE_URL (the API host, defaults to https://ingest.rustrak.pseekoo.io; the dashboard host is the same domain without the ingest. prefix and is auto-derived for triage links) and RUSTRAK_PROJECT_ID for the default project scope.
• Sentry: SENTRY_AUTH_TOKEN; optionally SENTRY_BASE_URL for self-hosted Sentry-compatible APIs.
• Bugsink (ingestion/reads only): BUGSINK_API_TOKEN plus SENTRY_DSN or BUGSINK_HOST.

These values are resolved through explicit env vars first, then Locke/Vaultwarden when ojiichan[vault] is installed.

Diagnostics DSL for agents

Annotate code paths so coding agents know where to look for errors:

from ojiichan import diagnostic, hint

@diagnostic(hint(
    operation="matrix_exchange",
    topic="auth",
    failure=True,
    issue_backend="bugsink",
    runbook="docs/runbooks/matrix-auth.md",
))
def exchange_matrix_token(...):
    ...

Or use a nearby comment that agents can parse/read:

# ojiichan: operation=matrix_exchange topic=auth failure=true issue_backend=bugsink tags=matrix,auth

The comment form is recognized with Python/shell (#), C/Rust/TS (//, ///, //!), and block/JSDoc (/* … */, *) markers, so the same annotation works across Python, TypeScript, and Rust source.

Hints line up with ELK fields (operation, topic, failure) and issue tooling (issue_backend, issue_query, runbook) so an agent can jump from code to logs/issues quickly.

MCP server

Ojiichan also ships a local stdio MCP server so coding agents can query diagnostics and run repeatable test/build checks without hardcoding shell snippets.

Run it manually:

uv run ojiichan-mcp

Example MCP client config:

{
  "mcpServers": {
    "ojiichan": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "ojiichan[vault]",
        "ojiichan-mcp"
      ]
    }
  }
}

Exposed tools:

• elk_health
• elk_logs
• emit_elk_event
• bugsink_health
• bugsink_issues
• parse_diagnostic_annotation
• bugsink_resolve_issue (returns "not supported" message)
• sentry_resolve_issue
• rustrak_resolve_issue
• rustrak_health
• rustrak_issues
• scaffold_observability (renders TypeScript/Rust setup files)
• create_bead_from_issue
• xcode_build
• xcode_test

For Xcode projects, an agent can call xcode_test with a local project_path, scheme, and destination.

Release

Publishing is handled by GitLab CI in the public martin-wieser/ojiichan repository:

• pushes to the default branch publish a PEP 440 dev build to the GitLab PyPI registry;
• tags matching vX.Y.Z publish the release to the GitLab PyPI registry and to pypi.org;
• tagged releases require PYPI_API_TOKEN in GitLab CI variables.

To release the current version:

VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
git tag "v${VERSION}"
git push origin main --tags

Notes

• Bugsink ingestion uses the normal Sentry SDK via SENTRY_DSN.
• Bugsink issue reads use the canonical read API at /api/canonical/0/issues/ and require BUGSINK_API_TOKEN.
• Issue resolution uses Sentry's /api/0/issues/{issue_id}/ PUT API and Rustrak's /api/projects/{project_id}/issues/{issue_id} PATCH API. Bugsink resolution is intentionally disabled.
• Beads integration is intentionally optional; ojiichan.beads shells out only when bead/beads is installed.
• The public distribution and import package are both ojiichan.