Telemetry

App code reads the host-bound aggregate with:

const summary = await opencloud.telemetry.summary();

The six surfaces are page, rest, storage, realtime, function, and cron. Each surface has:

• lastActivityAt
• requests24h
• errors24h
• lastStatus

Freshness lives at activity.telemetry, not at the top level:

const {
  status,
  latestIngestedAt,
  ingestionLagSeconds,
  sampledEntries,
  truncated,
} = summary.activity.telemetry;

Use usage?.completeness and timestamps when showing storage/user rollups.

Honest status

function telemetryLabel(summary) {
  const source = summary.activity.telemetry;
  if (source.status === "unavailable") return "Telemetry unavailable";
  if (source.truncated) return "Partial sample";
  if (!source.latestIngestedAt) return "No recent evidence";
  return `Ingested ${new Date(source.latestIngestedAt).toLocaleString()}`;
}

Do not label an absent surface “healthy.” Read the exact SDK response.

Builders can also inspect scoped control-plane logs and usage:

"$OPENCLOUD_CLI" logs "$APP_ID" --level error
"$OPENCLOUD_CLI" usage "$APP_ID"

Product metrics and alerts

Use manifest-declared custom counters or gauges only for product signals the platform cannot derive. Dimensions must be small, fixed enums:

observability:
  metrics:
    - name: tasks_created
      type: counter
      dimensions:
        assignee_type:
          values: [parent, child]

await opencloud.telemetry.increment("tasks_created", 1, {
  dimensions: { assignee_type: "child" },
  idempotencyKey: `task-created:${task.id}`,
});

Agents use the app-scoped Agent Feed and fixed threshold rules rather than Grafana, PromQL, or LogQL. Read the complete telemetry and alert contract.