docs(observability): publish local workspace job profiling guidance

[DecisionNerd]

Problem

Local telemetry must lead a developer from “this job is slow” to the responsible stage or wait without requiring an observability platform.

Objective

Publish an executable local gf workspace job profiling guide, signal catalog, and bottleneck interpretation workflow.

Requirements

• Document feat(observability): establish Rust-owned local workspace job telemetry #886 local enablement, no-global-provider ownership, explicit flush/shutdown, bounds, privacy, and disabled default.
• Publish one validated catalog for feat(observability): establish Rust-owned local workspace job telemetry #886/feat(observability): trace local workspace job stages and contention #887/feat(observability): summarize local workspace job bottlenecks #888/feat(observability): profile Hub clone as a local workspace job #922: job family, stage/wait/outcome enums, names, units, timing semantics, nesting, cardinality, and privacy.
• Provide a local workflow using structured stdout/file and/or a local collector as selected in feat(observability): establish Rust-owned local workspace job telemetry #886; require no hosted or paid service.
• Show how to distinguish queue-bound, lock/contention-bound, compute-bound, filesystem/sync-bound, provider/network-bound, retry-bound, and failure-heavy jobs.
• Explain total elapsed, queue delay, active duration, stage/wait totals, overlap, residual/unattributed time, attempts, and exact byte/record fields.
• Include examples for a general workspace job and Hub clone.
• Provide a troubleshooting checklist when timing is missing, residual time is high, or the local exporter fails.

Acceptance Criteria

• A clean developer can enable local telemetry, run a fixture job, inspect its trace, and identify the intentionally delayed stage.
• A local session summary correctly identifies intentionally queue-bound, compute-bound, and sync-bound fixtures.
• Machine-readable catalog validation fails on unversioned name/unit/enum/timing drift.
• Examples run in CI without remote services and contain no prohibited canaries.
• Guidance never presents wall time as CPU time or local session counters as billing/long-term usage.

BDD Completion Scenarios

Scenario: A developer finds a slow stage
Given a deliberately slowed local job
When the profiling guide is followed
Then the responsible finite stage or wait is identified from local output.

Scenario: No collector is available
Given only local gf tooling
When the in-process/session output is used
Then useful bottleneck evidence remains available without remote export.

Scenario: Privacy is audited
Given traces from sensitive canary inputs
When local export is inspected
Then no path, repository/project identity, query, credential, UUID, property, or graph/result content appears.

Testing

Executable local examples; catalog validation; deliberately slow fixture assertions; privacy snapshots/mutation tests; exporter-failure runbook path.

Documentation

Update existing observability/CLI guides; add one canonical local job catalog and profiling runbook.

Non-Goals

Hosted dashboards, managed collectors, paid resources, production alerting, billing, managed-cloud usage, or user-specific analytics.

Relationships

Blocked by #886, #887, #888, and #922; closes M10 local profiling evidence.

Profiling Guide Focus

Teach developers how to answer: which GraphForge APIs ran and in what order; which call was slow; how much authoritative CPU time it consumed; whether time was actually queue/I/O/network/lock waiting; which extensions were invoked; and how import/export time and volume split across validation, encoding/decoding, transfer, storage, and publication.

Include a test-extension example shaped for future XYG adoption, explain unavailable CPU measurements without substitutes, and show both a slow import and a slow export diagnosis using local tooling.

Trace-reading model

Document that every span is a completed command or operation. Show a single API call, a command with sequential child operations, a recursively composed operation, and concurrent children. Explain parent latency versus child and self time so developers do not double-count nested spans.

Workspace statistics usage

Document the direct API and CLI path for an immediate count-and-size answer, then show how periodic telemetry tracks those same values over time. Define count consistency, included disk files/generations, logical size versus disk footprint versus volume capacity, freshness, recovery reconciliation, and unavailable platform fields.