make-app-observability

make-app-observability

All newly created Make Apps are connected to Trace ID by default. For existing Apps, when this task involves business requests, AI transport, error exits, or release gates, the relevant Trace links should be checked and missing parts completed; for unrelated changes, only report discovered gaps and do not expand the scope of this task without authorization. The default scope of Trace ID is the App's business requests and their error exits, including AI JSON, SSE, and binary transport when enabled. Static resources and OAuth callbacks are not within the scope of the UI business request adapter.

Responsibilities and boundaries

This Skill is responsible for Trace ID generation, propagation, correlated logs, error classification, and unified display across the UI, optional Service, and Make Gateway.@qfei-design/make-app-observability Provides the error presentation model and React components; it does not send requests, create Spans, pass Headers, record logs, or configure exporters. Installing this package must not be equated with completing the Trace link, nor may having only Trace ID correlation be claimed as being connected to a centralized Trace backend.

• Authentication requests and the cookie/session mechanism are delegated to make-app-auth; inject the tracing Header in its shared authenticated request adapter, and do not write separate raw requests or browser token logic.
• Service routing, UI-Service business contracts, and the Make adapter are delegated to make-app-service; this Skill defines the Trace invariants across these boundaries.
• AI routing, streaming events, and cancellation semantics are delegated to make-ai-assistant; its authenticated JSON, SSE, and binary transport follow the same tracing contract.
• Release scripts and delivery gates are delegated to make-app-runtime; that Skill calls this Skill's auditor.
• Mounting the global error exit at the persistent application root, coordinating layers with the host overlay, and accepting real Shell visibility are delegated to makeui; this Skill is responsible for handing safe structured request errors to that exit.0.1.8+ The public package is responsible for the default positioning, error cards, and Trace ID display rules for desktop and mobile viewports; the host does not override the default positioning.

Default integration process

1. Determine the App's request topology: UI directly connects to the Make Gateway, or UI -> Service -> Make Gateway. Both topologies must go through a shared, authenticated UI request adapter.
2. At the start of each business request in the UI, create a valid W3C Trace context and save this request's 128-bit non-zero Trace ID. The request Header writes both traceparent and the X-Log-Idequal to its trace-id; the success or failure of the same request uses the ID saved at creation time, and retries are treated as new network attempts that recreate and retain the corresponding ID. Do not pass Trace information via URL query.
3. For Service-fronted Apps, validate the inbound Header at the request entry point, and generate a safe Trace ID when it is missing or invalid; all responses return X-Log-Id. When forwarding to the Make Gateway, use only the validated and consistent tracing Header, and Service security logs carry the same traceId. In direct-connect mode, the shared UI adapter sends the Header to the Gateway.
4. The unified error exit distinguishes HTTP non-2xx, network exceptions, and HTTP 2xx business code exceptions. When a response is received, record the actual HTTP status code in the Span; business code failures and HTTP non-2xx are marked as errors, and network exceptions do not fabricate a status code. Keep a safe kind/status/title/description/traceIdbetween the request layer and Providers such as permissions, Schema, and the error exit, and do not degrade it into a string containing only text. Use the public package's MakeAppErrorNotice, and the global error queue must be handled by a MakeAppErrorNoticeViewport Wrapper; the inline error card on the page can be used independently. For the three types of real request failures, as long as they carry a valid Trace ID, a copyable ID is displayed. On failure, prioritize preserving the ID created for this request to avoid losing correlation information due to an unresponsive network error.
5. When the App uses AI transport, JSON, SSE, file, and binary requests also send these two Headers; for HTTP non-2xx, even if there is a response body, the Span must be marked as an error. It cannot restore the old practice of passing Trace through __traceparent and other query parameters.
6. Apps newly integrated or with the error exit modified in this change use the actually installed @qfei-design/make-app-observability@0.1.8+; this is the delivery baseline for the desktop top Toast, dual-platform portal, and full content visibility. First add behavior tests, then run scripts/audit-trace-contract.mjs and the App's existing tests. Audit checks of the declared version and source code wiring cannot replace verification of the actually installed version, real requests, and assertions of error card visibility under the real AppShell.

Read as needed

Work	Read
Install the public package, public entry points, error states, and desktop/mobile global exits	references/package-integration.md
Trace links and security boundaries for UI, Service, Gateway, and AI	references/trace-chain.md
Behavior tests, static audits, release checks, and troubleshooting	references/testing-and-audit.md

When installing or upgrading, first read from the installed package of the target App package.ai.json read readOrder, and read the public documentation in the declared order; do not deep-import from the package's src or dist , and do not treat the examples written in this Skill as a public API higher than the target installed version.

Delivery conditions

• The project-level release check for a new Make App includes trace:audit; before release, pass both the applicable behavior tests and the audit. Existing Apps use their own compatible runtime and release commands, and package managers are not forcibly migrated for integrating tracing.
• Audit command:node skills/make-app-observability/scripts/audit-trace-contract.mjs <project-root> --mode auto. Only scripts copied locally into the App project may be written into the project package.json, and do not reference the Skill's absolute path on the developer's machine.
• Do not log or pass to the UI Authorization, Cookies, tokens, business request bodies, AI prompts, or raw internal errors. Logs only write safe routes, methods, statuses, error categories, and traceId。