Spaces:
Running
Running
File size: 7,571 Bytes
4ee7081 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 | {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://huggingface.co/datasets/szl-holdings/uds-observability/schemas/span_schema.json",
"title": "UDS Span",
"description": "A single UDS (Unified Data Substrate) observability span, shaped to the OpenTelemetry Trace Data Model (https://opentelemetry.io/docs/specs/otel/trace/api/) and extended with SZL governance fields for SLSA attestation linkage.",
"type": "object",
"required": [
"trace_id",
"span_id",
"component",
"kind",
"timestamp_utc",
"duration_ms",
"status",
"synthetic"
],
"properties": {
"trace_id": {
"type": "string",
"description": "128-bit globally unique trace identifier, hex-encoded (32 chars). Conforms to W3C Trace Context (https://www.w3.org/TR/trace-context/#trace-id). Groups all spans belonging to a single end-to-end request.",
"pattern": "^[0-9a-f]{32}$",
"examples": ["4bf92f3577b34da6a3ce929d0e0e4736"]
},
"span_id": {
"type": "string",
"description": "64-bit unique span identifier within the trace, hex-encoded (16 chars). Conforms to the OpenTelemetry SpanContext spec (https://opentelemetry.io/docs/specs/otel/trace/api/#spancontext).",
"pattern": "^[0-9a-f]{16}$",
"examples": ["00f067aa0ba902b7"]
},
"parent_span_id": {
"type": ["string", "null"],
"description": "Span ID of the parent span, or null for a root span. Used to reconstruct the directed-acyclic-graph (DAG) of spans within a trace per the OpenTelemetry Traces spec (https://opentelemetry.io/docs/concepts/signals/traces/).",
"pattern": "^([0-9a-f]{16})?$",
"examples": ["5e8b6c0d1a4f2e9d", null]
},
"component": {
"type": "string",
"description": "The SZL mesh component that emitted the span. One of the four UDS mesh components versioned at commit 25a7e53 (uds-v0.2.0).",
"enum": ["a11oy", "amaru", "rosie", "sentra"],
"examples": ["a11oy"]
},
"component_commit": {
"type": "string",
"description": "Short-form commit SHA of the specific component release that emitted the span. Used for supply-chain traceability per SLSA provenance requirements (https://slsa.dev/spec/v1.0/provenance).",
"examples": ["cbf10510", "1ceefeb9", "29982b68", "ed6bca8f"]
},
"attestation_id": {
"type": ["string", "null"],
"description": "Opaque string identifier linking this span to a governance receipt in the DSSE-wrapped receipts file. Null when the span has not yet been attested. A non-null value indicates the span is 'well-attested' for the binary classification task defined in eval_starter.ipynb.",
"examples": ["att-a11oy-001", null]
},
"dsse_envelope_b64": {
"type": ["string", "null"],
"description": "Base64url-encoded DSSE (Dead Simple Signing Envelope, https://github.com/secure-systems-lab/dsse) payload. Contains the in-toto attestation predicate for this span when present. Null for unattested spans. The PAE (Pre-Authentication Encoding) format follows the DSSE v1 spec: 'DSSEv1 SP LEN(type) SP type SP LEN(payload) SP payload'.",
"contentEncoding": "base64url",
"examples": [null]
},
"kind": {
"type": "string",
"description": "UDS span kind. Extends the OpenTelemetry SpanKind vocabulary (https://opentelemetry.io/docs/specs/otel/trace/api/#spankind) with UDS-specific governance and agent operation kinds. Core OTel kinds: CLIENT, SERVER, INTERNAL, PRODUCER, CONSUMER.",
"enum": [
"agent_call",
"tool_invocation",
"attestation_emit",
"receipt_verify",
"sbom_probe",
"policy_eval",
"sensor_ingest",
"model_inference",
"data_fetch",
"receipt_chain_append",
"CLIENT",
"SERVER",
"INTERNAL",
"PRODUCER",
"CONSUMER"
],
"examples": ["agent_call", "attestation_emit"]
},
"timestamp_utc": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 / RFC 3339 UTC timestamp marking the start of the span. Aligns with OTel Span start_time_unix_nano semantics (https://opentelemetry.io/docs/specs/otel/trace/api/#span-start).",
"examples": ["2026-01-15T10:23:45.123456Z"]
},
"duration_ms": {
"type": "number",
"description": "Span duration in milliseconds (float). Derived from OTel start_time_unix_nano and end_time_unix_nano. Must be >= 0.",
"minimum": 0,
"examples": [42.7, 1023.1]
},
"status": {
"type": "string",
"description": "Span status per the OpenTelemetry Status spec (https://opentelemetry.io/docs/specs/otel/trace/api/#set-status). Unset = operation completed without error; Error = error occurred; Ok = explicitly marked error-free by the developer.",
"enum": ["Unset", "Ok", "Error"],
"examples": ["Ok"]
},
"status_message": {
"type": ["string", "null"],
"description": "Human-readable description of the status, populated when status is Error.",
"examples": [null, "Policy check failed: missing required field 'subject_sha256'"]
},
"attributes": {
"type": "object",
"description": "Key-value pairs carrying span-specific metadata. Values must be string, boolean, number, or homogeneous arrays thereof per the OTel Attributes spec (https://opentelemetry.io/docs/specs/otel/common/). SZL-specific keys are prefixed 'szl.'.",
"additionalProperties": {
"oneOf": [
{"type": "string"},
{"type": "boolean"},
{"type": "number"},
{"type": "array", "items": {"type": "string"}},
{"type": "array", "items": {"type": "number"}},
{"type": "array", "items": {"type": "boolean"}}
]
},
"examples": [{"szl.component_version": "0.2.0", "szl.slsa_level": 2, "http.method": "POST"}]
},
"events": {
"type": "array",
"description": "Timestamped annotations on the span, per the OTel SpanEvent spec (https://opentelemetry.io/docs/specs/otel/trace/api/#add-events). Useful for recording discrete governance checkpoints mid-span.",
"items": {
"type": "object",
"required": ["name", "timestamp_utc"],
"properties": {
"name": {"type": "string"},
"timestamp_utc": {"type": "string", "format": "date-time"},
"attributes": {"type": "object"}
}
}
},
"slsa_level": {
"type": ["integer", "null"],
"description": "Observed SLSA level (https://slsa.dev/spec/v1.0/levels) at span emission time. Integer 0–3 per the SLSA v1.0 track taxonomy. Null when SLSA posture is unknown.",
"minimum": 0,
"maximum": 3,
"examples": [2, null]
},
"mesh_commit": {
"type": "string",
"description": "The uds-mesh commit SHA at which this span was captured. Canonical anchor: github.com/szl-holdings/uds-mesh @ uds-v0.2.0 (commit 25a7e53).",
"examples": ["25a7e53"]
},
"split": {
"type": "string",
"description": "Dataset split assignment: train, test, or validation.",
"enum": ["train", "test", "validation"],
"examples": ["train"]
},
"synthetic": {
"type": "boolean",
"description": "True for all records in this dataset release. All spans are synthetic-but-realistic examples generated to match the statistical distribution of production UDS mesh traffic. No live production data is included in v0.1.0.",
"const": true
}
},
"additionalProperties": false
}
|