make-app-observability

Original：🇨🇳 Chinese

Translated

2 scripts

Use when creating, integrating, reviewing, or debugging a Make App's default Trace ID chain, traceparent and X-Log-Id propagation, safe correlated logs, or @qfei-design/make-app-observability error notices. Every new Make App includes this baseline even when the user does not mention observability. Covers direct-gateway and Service-fronted Apps and AI transports when present. Does not own authentication, Service route design, AI protocol, tracing backend/exporter deployment, runtime packaging, or page layout.

8installs

Sourceqfeius/make-platform-skills

Added on2026-10-09

NPX Install

npx skill4agent add qfeius/make-platform-skills make-app-observability

SKILL.md Content (Chinese)

View Translation Comparison →

make-app-observability

All newly created Make Apps have Trace ID integrated by default. For existing Apps, if the current task involves business requests, AI transport, error exits, or release gates, the relevant Trace chain should be checked and missing links filled in; for unrelated changes, only report the discovered missing parts and do not arbitrarily expand the scope of the current task. The default scope of Trace ID covers the App's business requests and their error exits, including AI JSON, SSE, and binary transports 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 logging, error classification, and unified display across UI, optional Service, and Make Gateway.

@qfei-design/make-app-observability

provides error presentation models and React components; it does not send requests, create Spans, pass Headers, record logs, or configure exporters. Installing this package cannot be equated with completing the Trace chain, nor can having only Trace ID correlation be claimed as having integrated a centralized Trace backend.

Authentication requests and cookie/session mechanisms are handled by
```
make-app-auth
```
; inject tracing Headers into its shared authenticated request adapter, and do not write separate bare requests or browser token logic.
Service routing, UI-Service business contracts, and Make adapters are handled by
```
make-app-service
```
; this Skill defines Trace invariants across these boundaries.
AI routing, streaming events, and cancellation semantics are handled by
```
make-ai-assistant
```
; its authenticated JSON, SSE, and binary transports follow the same tracing contract.
Release scripts and delivery gates are handled by
```
make-app-runtime
```
; that Skill calls the auditor of this Skill.
Page layout and the location of error exits are handled by
```
makeui
```
; error cards and Trace ID display rules are the responsibility of the common package.

Default Integration Process

Determine the App's request topology: UI directly connects to Make Gateway, or
```
UI -> Service -> Make Gateway
```
. Both topologies must go through a shared, authenticated UI request adapter.
Create a valid W3C Trace context at the start of each business request in the UI, and save the 128-bit non-zero Trace ID for this request. Write both
```
traceparent
```
and
```
X-Log-Id
```
(which equals the trace-id in traceparent) to the request Header; use the saved ID for both success and failure of the same request, and recreate and retain the corresponding ID for retries as new network attempts. Do not pass Trace information via URL query.
For Service-fronted Apps, validate inbound Headers at the request entry, and generate a secure Trace ID if they are missing or invalid; all responses return
```
X-Log-Id
```
. When forwarding to Make Gateway, only use validated and consistent tracing Headers, and Service security logs carry the same
```
traceId
```
. For direct connection mode, the shared UI adapter sends Headers to the Gateway.
The unified error exit distinguishes between HTTP non-2xx errors, 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 errors are marked as errors, and no status code is fabricated for network exceptions. Use
```
MakeAppErrorNotice
```
from the common package; only HTTP and network errors display a copyable Trace ID. In case of failure, prioritize retaining the ID created for this request to avoid losing correlation information for network errors with no response.
When the App uses AI transport, these two Headers are also sent for JSON, SSE, file, and binary requests; even if there is a response body for HTTP non-2xx errors, the Span should be marked as an error. Do not revert to the old practice of passing Trace via query parameters such as
```
__traceparent
```
.
First supplement behavioral tests, then run
```
scripts/audit-trace-contract.mjs
```
and the App's existing tests. Auditing is a source code wiring check and cannot replace end-to-end assertions of real requests.

On-Demand Reading

Task	Read
Install common packages, public entries, error cards, and mobile global exits	`references/package-integration.md`
Trace chain and security boundaries for UI, Service, Gateway, and AI	`references/trace-chain.md`
Behavioral testing, static auditing, release checks, and troubleshooting	`references/testing-and-audit.md`

During installation or upgrade, first read

readOrder

from the

package.ai.json

of the target App's installed packages, and read the public documentation in the declared order; do not import deeply from

src

or

dist

inside the package, nor treat examples written by this Skill as public APIs higher than the target installed version.

Delivery Conditions

Project-level release checks for newly created Make Apps include
```
trace:audit
```
; applicable behavioral tests and audits must be passed before release. Existing Apps use their own compatible runtime and release commands, and package manager migration is not mandatory for tracing integration.
Audit command:
```
node skills/make-app-observability/scripts/audit-trace-contract.mjs <project-root> --mode auto
```
. Only scripts copied locally to the App project can be written to the project's
```
package.json
```
; do not reference the absolute path of the Skill on the developer's machine.
Do not record or pass
```
Authorization
```
, Cookie, token, business request body, AI prompts, or raw internal errors to the UI. Logs only include safe routes, methods, statuses, error categories, and
```
traceId
```
.

make-app-observability

NPX Install

Tags

SKILL.md Content (Chinese)

make-app-observability

Responsibilities and Boundaries

Default Integration Process

On-Demand Reading

Delivery Conditions