Observability

ObjectOS operations need both infrastructure signals and application signals. The framework provides request-id, metrics, error reporter, and audit primitives; the deployment decides where to export them.

Request identity

Every production deployment should propagate or generate a request id:

X-Request-Id

Use it to correlate:

• ingress logs;
• ObjectOS logs;
• database slow queries;
• error reports;
• customer support tickets.

Metrics and errors

The runtime exposes pluggable metrics and error reporter interfaces. Wire them to the customer's chosen system, such as Prometheus, OpenTelemetry, Datadog, Sentry, or another approved backend.

Track at least:

Minimal Prometheus example

ObjectOS exposes a Prometheus-compatible metrics endpoint when the metrics service is enabled:

# prometheus.yml
scrape_configs:
  - job_name: objectos
    metrics_path: /metrics
    static_configs:
      - targets: ['objectos:3000']

Useful starter alerts:

groups:
  - name: objectos
    rules:
      - alert: ObjectOS5xxSpike
        expr: |
          sum(rate(http_requests_total{status=~"5.."}[5m]))
            / sum(rate(http_requests_total[5m])) > 0.02
        for: 5m
        annotations:
          summary: "ObjectOS 5xx rate above 2% for 5 minutes"

Cold starts are not on that list. The kernel is built once, at startup, and the process reports ready only afterwards — there is no steady-state cache-miss signal to alert on, so alert on readiness instead.

Auth failures are not on it either. The runtime's metric registry covers HTTP, storage, cache, background jobs and the package registry; none of those counts a rejected credential, so there is no series to alert on. Counting 401/403 out of http_requests_total is not a substitute for one: the sign-in endpoints do not feed that counter, a rejected API key is indistinguishable from a request that carried no credential at all, and both statuses are dominated by ordinary permission denials against users who authenticated perfectly well. Review sign-in activity in Setup's Auth audit view instead — see Audit Logs.

For OpenTelemetry, set OS_OBS_EXPORTER=otlp and OS_OTLP_ENDPOINT (e.g. https://<collector>/otlp) and ObjectOS will emit traces and metrics in OTLP format. The exporter defaults to noop (zero runtime cost), so OTLP export is opt-in — setting an endpoint without OS_OBS_EXPORTER=otlp emits nothing. Use OS_OBS_EXPORTER=console or json for local debugging, and OS_OBS_DEPLOYMENT_ENV to tag the deployment (defaults to production). The shape of spans matches the request flow.

Audit logs

When the audit capability is enabled, ObjectOS writes audit records to sys_audit_log.

Use audit logs for:

• permission-sensitive changes;
• settings changes;
• user/session investigation;
• integration activity;
• denied access analysis.

For regulated environments, make the audit table append-only at the database or storage layer and define a retention policy.

For the full field reference, preset views, and the sibling diagnostics logs, see Audit Logs.

Setup diagnostics

Setup exposes operational surfaces such as:

• Sessions;
• Audit Logs;
• Notifications;
• Webhook Deliveries when webhooks are enabled;
• System and Security overview dashboards.

These are intended for operators and support engineers, not only developers.