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"

      - alert: ObjectOSAuthFailureSpike
        expr: rate(auth_failures_total[5m]) > 5
        for: 10m
        annotations:
          summary: "Sustained auth failure rate — check for misconfiguration or attack"

      - alert: ObjectOSKernelColdStartHigh
        expr: rate(kernel_cache_misses_total[15m]) > 1
        for: 15m
        annotations:
          summary: "Frequent project kernel cold starts — consider raising OS_KERNEL_CACHE_SIZE"

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.

Console diagnostics

The Console 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.