@ancplua/qyl-api-schema 0.2.0

package/otel/resource.tsp

@@ -0,0 +1,257 @@
+// =============================================================================
+// ANcpLua v2.0 - OpenTelemetry Resource Model
+// =============================================================================
+// Resource attributes identifying the entity producing telemetry.
+// =============================================================================
+
+import "../common/types.tsp";
+import "./enums.tsp";
+
+using Qyl.Api.Contracts.Common;
+
+namespace Qyl.Api.Contracts.OTel.Resource;
+
+// =============================================================================
+// Resource Model
+// =============================================================================
+
+@doc("Resource describes the entity producing telemetry")
+model Resource {
+  @doc("Service name (required)")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Service.Name)
+  serviceName: string;
+
+  @doc("Service namespace for grouping")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Service.Namespace)
+  serviceNamespace?: string;
+
+  @doc("Service instance ID (unique per instance)")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Service.InstanceId)
+  serviceInstanceId?: string;
+
+  @doc("Service version")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Service.Version)
+  serviceVersion?: SemVer;
+
+  @doc("Telemetry SDK name")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Telemetry.SdkName)
+  telemetrySdkName?: string;
+
+  @doc("Telemetry SDK language")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Telemetry.SdkLanguage)
+  telemetrySdkLanguage?: Enums.TelemetrySdkLanguage;
+
+  @doc("Telemetry SDK version")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Telemetry.SdkVersion)
+  telemetrySdkVersion?: SemVer;
+
+  @doc("Auto-instrumentation agent name")
+  @encodedName("application/json", "telemetry.auto.version")
+  telemetryAutoVersion?: SemVer;
+
+  @doc("Deployment environment (e.g., production, staging)")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Deployment.EnvironmentName)
+  deploymentEnvironment?: string;
+
+  @doc("Cloud provider")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Cloud.Provider)
+  cloudProvider?: CloudProvider;
+
+  @doc("Cloud region")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Cloud.Region)
+  cloudRegion?: string;
+
+  @doc("Cloud availability zone")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Cloud.AvailabilityZone)
+  cloudAvailabilityZone?: string;
+
+  @doc("Cloud account ID")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Cloud.AccountId)
+  cloudAccountId?: string;
+
+  @doc("Cloud platform (e.g., aws_ecs, gcp_cloud_run)")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Cloud.Platform)
+  cloudPlatform?: string;
+
+  @doc("Host name")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Host.Name)
+  hostName?: string;
+
+  @doc("Host ID")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Host.Id)
+  hostId?: string;
+
+  @doc("Host type (e.g., n1-standard-1)")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Host.Type)
+  hostType?: string;
+
+  @doc("Host architecture (e.g., amd64, arm64)")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Host.Arch)
+  hostArch?: HostArch;
+
+  @doc("Operating system type")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Os.Type)
+  osType?: OsType;
+
+  @doc("Operating system description")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Os.Description)
+  osDescription?: string;
+
+  @doc("Operating system version")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Os.Version)
+  osVersion?: string;
+
+  @doc("Process ID")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Process.Pid)
+  processPid?: int64;
+
+  @doc("Process executable name")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Process.ExecutableName)
+  processExecutableName?: string;
+
+  @doc("Process command line")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Process.CommandLine)
+  processCommandLine?: string;
+
+  @doc("Process runtime name")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Process.RuntimeName)
+  processRuntimeName?: string;
+
+  @doc("Process runtime version")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Process.RuntimeVersion)
+  processRuntimeVersion?: string;
+
+  @doc("Container ID")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Container.Id)
+  containerId?: string;
+
+  @doc("Container name")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Container.Name)
+  containerName?: string;
+
+  @doc("Container image name")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Container.ImageName)
+  containerImageName?: string;
+
+  @doc("Container image tag")
+  @encodedName("application/json", "container.image.tag")
+  containerImageTag?: string;
+
+  @doc("Kubernetes cluster name")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.K8s.ClusterName)
+  k8sClusterName?: string;
+
+  @doc("Kubernetes namespace")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.K8s.NamespaceName)
+  k8sNamespaceName?: string;
+
+  @doc("Kubernetes pod name")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.K8s.PodName)
+  k8sPodName?: string;
+
+  @doc("Kubernetes pod UID")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.K8s.PodUid)
+  k8sPodUid?: string;
+
+  @doc("Kubernetes deployment name")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.K8s.DeploymentName)
+  k8sDeploymentName?: string;
+
+  @doc("Additional resource attributes")
+  attributes?: Attribute[];
+
+  @doc("Dropped attributes count")
+  @encodedName("application/json", "dropped_attributes_count")
+  droppedAttributesCount?: Count;
+}
+
+// =============================================================================
+// Resource-Related Enums
+// =============================================================================
+
+@doc("Cloud provider types")
+enum CloudProvider {
+  @doc("Alibaba Cloud")
+  alibabaCloud: "alibaba_cloud",
+
+  @doc("Amazon Web Services")
+  aws: "aws",
+
+  @doc("Microsoft Azure")
+  azure: "azure",
+
+  @doc("Google Cloud Platform")
+  gcp: "gcp",
+
+  @doc("Heroku")
+  heroku: "heroku",
+
+  @doc("IBM Cloud")
+  ibmCloud: "ibm_cloud",
+
+  @doc("Tencent Cloud")
+  tencentCloud: "tencent_cloud",
+}
+
+@doc("Host architecture types")
+enum HostArch {
+  @doc("AMD64 / x86_64")
+  amd64: "amd64",
+
+  @doc("ARM32")
+  arm32: "arm32",
+
+  @doc("ARM64 / aarch64")
+  arm64: "arm64",
+
+  @doc("Itanium")
+  ia64: "ia64",
+
+  @doc("PowerPC 32-bit")
+  ppc32: "ppc32",
+
+  @doc("PowerPC 64-bit")
+  ppc64: "ppc64",
+
+  @doc("IBM z/Architecture")
+  s390x: "s390x",
+
+  @doc("x86 32-bit")
+  x86: "x86",
+}
+
+@doc("Operating system types")
+enum OsType {
+  @doc("Microsoft Windows")
+  windows: "windows",
+
+  @doc("Linux")
+  linux: "linux",
+
+  @doc("Apple macOS")
+  darwin: "darwin",
+
+  @doc("FreeBSD")
+  freebsd: "freebsd",
+
+  @doc("NetBSD")
+  netbsd: "netbsd",
+
+  @doc("OpenBSD")
+  openbsd: "openbsd",
+
+  @doc("DragonFly BSD")
+  dragonflybsd: "dragonflybsd",
+
+  @doc("HP-UX")
+  hpux: "hpux",
+
+  @doc("AIX")
+  aix: "aix",
+
+  @doc("Oracle Solaris")
+  solaris: "solaris",
+
+  @doc("IBM z/OS")
+  zOs: "z_os",
+}

package/otel/span.tsp

@@ -0,0 +1,307 @@
+// =============================================================================
+// ANcpLua v2.0 - OpenTelemetry Span Model
+// =============================================================================
+// Distributed tracing span representation following OTel specification.
+// =============================================================================
+
+import "@typespec/http";
+import "@typespec/openapi";
+import "../common/types.tsp";
+import "./enums.tsp";
+import "./resource.tsp";
+
+using TypeSpec.Http;
+using TypeSpec.OpenAPI;
+using Qyl.Api.Contracts.Common;
+using Qyl.Api.Contracts.OTel.Enums;
+using Qyl.Api.Contracts.OTel.Resource;
+
+namespace Qyl.Api.Contracts.OTel.Traces;
+
+// =============================================================================
+// Span Model
+// =============================================================================
+
+@doc("OpenTelemetry Span representing a single operation in a distributed trace")
+model Span {
+  @doc("Unique span identifier (16 hex chars)")
+  @key
+  @encodedName("application/json", "span_id")
+  spanId: SpanId;
+
+  @doc("Trace identifier (32 hex chars)")
+  @encodedName("application/json", "trace_id")
+  traceId: TraceId;
+
+  @doc("Parent span identifier (null for root spans)")
+  @encodedName("application/json", "parent_span_id")
+  parentSpanId?: SpanId;
+
+  @doc("W3C trace state")
+  @encodedName("application/json", "trace_state")
+  traceState?: TraceState;
+
+  @doc("Human-readable span name")
+  @minLength(1)
+  name: string;
+
+  @doc("Span kind")
+  kind: SpanKind;
+
+  @doc("Start timestamp in nanoseconds since epoch")
+  @encodedName("application/json", "start_time_unix_nano")
+  startTimeUnixNano: UnixNanos;
+
+  @doc("End timestamp in nanoseconds since epoch")
+  @encodedName("application/json", "end_time_unix_nano")
+  endTimeUnixNano: UnixNanos;
+
+  @doc("Span attributes")
+  attributes?: Attribute[];
+
+  @doc("Dropped attributes count")
+  @encodedName("application/json", "dropped_attributes_count")
+  droppedAttributesCount?: Count;
+
+  @doc("Span events (logs attached to span)")
+  events?: SpanEvent[];
+
+  @doc("Dropped events count")
+  @encodedName("application/json", "dropped_events_count")
+  droppedEventsCount?: Count;
+
+  @doc("Links to other spans")
+  links?: SpanLink[];
+
+  @doc("Dropped links count")
+  @encodedName("application/json", "dropped_links_count")
+  droppedLinksCount?: Count;
+
+  @doc("Span status")
+  status: SpanStatus;
+
+  @doc("Span flags")
+  flags?: int32;
+
+  @doc("Resource describing the entity that produced this span")
+  resource: Qyl.Api.Contracts.OTel.Resource.Resource;
+
+  @doc("Instrumentation scope")
+  @encodedName("application/json", "instrumentation_scope")
+  instrumentationScope?: InstrumentationScope;
+}
+
+@doc("Span status")
+model SpanStatus {
+  @doc("Status code")
+  code: SpanStatusCode;
+
+  @doc("Status message (only for ERROR status)")
+  message?: string;
+}
+
+@doc("Event occurring during a span's lifetime")
+model SpanEvent {
+  @doc("Event name")
+  @minLength(1)
+  name: string;
+
+  @doc("Event timestamp in nanoseconds since epoch")
+  @encodedName("application/json", "time_unix_nano")
+  timeUnixNano: UnixNanos;
+
+  @doc("Event attributes")
+  attributes?: Attribute[];
+
+  @doc("Dropped attributes count")
+  @encodedName("application/json", "dropped_attributes_count")
+  droppedAttributesCount?: Count;
+}
+
+@doc("Link to another span (e.g., batch processing)")
+model SpanLink {
+  @doc("Linked trace ID")
+  @encodedName("application/json", "trace_id")
+  traceId: TraceId;
+
+  @doc("Linked span ID")
+  @encodedName("application/json", "span_id")
+  spanId: SpanId;
+
+  @doc("Trace state of the linked span")
+  @encodedName("application/json", "trace_state")
+  traceState?: TraceState;
+
+  @doc("Link attributes")
+  attributes?: Attribute[];
+
+  @doc("Dropped attributes count")
+  @encodedName("application/json", "dropped_attributes_count")
+  droppedAttributesCount?: Count;
+
+  @doc("Link flags")
+  flags?: int32;
+}
+
+// =============================================================================
+// Trace Model (Collection of Spans)
+// =============================================================================
+
+@doc("Complete trace containing all related spans")
+model Trace {
+  @doc("Trace identifier")
+  @key
+  @encodedName("application/json", "trace_id")
+  traceId: TraceId;
+
+  @doc("All spans in this trace")
+  spans: Span[];
+
+  @doc("Root span of the trace")
+  @encodedName("application/json", "root_span")
+  rootSpan?: Span;
+
+  @doc("Total span count")
+  @encodedName("application/json", "span_count")
+  spanCount: int32;
+
+  @doc("Trace duration in nanoseconds")
+  @encodedName("application/json", "duration_ns")
+  durationNs: DurationNs;
+
+  @doc("Trace start time")
+  @encodedName("application/json", "start_time")
+  startTime: utcDateTime;
+
+  @doc("Trace end time")
+  @encodedName("application/json", "end_time")
+  endTime: utcDateTime;
+
+  @doc("Services involved in this trace")
+  services: string[];
+
+  @doc("Whether trace contains errors")
+  @encodedName("application/json", "has_error")
+  hasError: boolean;
+}
+
+// =============================================================================
+// Span Query Filters
+// =============================================================================
+
+@doc("Filter parameters for querying spans")
+model SpanQueryFilters {
+  @doc("Filter by trace ID")
+  @query
+  @encodedName("application/json", "trace_id")
+  traceId?: TraceId;
+
+  @doc("Filter by parent span ID")
+  @query
+  @encodedName("application/json", "parent_span_id")
+  parentSpanId?: SpanId;
+
+  @doc("Filter by span name (supports wildcards)")
+  @query
+  name?: string;
+
+  @doc("Filter by span kind")
+  @query
+  kind?: SpanKind;
+
+  @doc("Filter by service name")
+  @query
+  @encodedName("application/json", "service_name")
+  serviceName?: string;
+
+  @doc("Filter by status code")
+  @query
+  @encodedName("application/json", "status_code")
+  statusCode?: SpanStatusCode;
+
+  @doc("Minimum duration in nanoseconds")
+  @query
+  @encodedName("application/json", "min_duration_ns")
+  minDurationNs?: DurationNs;
+
+  @doc("Maximum duration in nanoseconds")
+  @query
+  @encodedName("application/json", "max_duration_ns")
+  maxDurationNs?: DurationNs;
+
+  @doc("Filter by attribute key-value pair")
+  @query
+  attribute?: string;
+}
+
+// =============================================================================
+// Span Aggregations
+// =============================================================================
+
+@doc("Aggregated span statistics")
+model SpanStats {
+  @doc("Total span count")
+  @encodedName("application/json", "total_count")
+  totalCount: Count;
+
+  @doc("Error count")
+  @encodedName("application/json", "error_count")
+  errorCount: Count;
+
+  @doc("Error rate (0.0 - 1.0)")
+  @encodedName("application/json", "error_rate")
+  errorRate: Ratio;
+
+  @doc("Average duration in nanoseconds")
+  @encodedName("application/json", "avg_duration_ns")
+  avgDurationNs: float64;
+
+  @doc("P50 duration in nanoseconds")
+  @encodedName("application/json", "p50_duration_ns")
+  p50DurationNs: DurationNs;
+
+  @doc("P90 duration in nanoseconds")
+  @encodedName("application/json", "p90_duration_ns")
+  p90DurationNs: DurationNs;
+
+  @doc("P99 duration in nanoseconds")
+  @encodedName("application/json", "p99_duration_ns")
+  p99DurationNs: DurationNs;
+
+  @doc("Minimum duration in nanoseconds")
+  @encodedName("application/json", "min_duration_ns")
+  minDurationNs: DurationNs;
+
+  @doc("Maximum duration in nanoseconds")
+  @encodedName("application/json", "max_duration_ns")
+  maxDurationNs: DurationNs;
+
+  @doc("Throughput (spans per second)")
+  @encodedName("application/json", "throughput_per_second")
+  throughputPerSecond: float64;
+
+  @doc("Stats grouped by service")
+  @encodedName("application/json", "by_service")
+  byService?: SpanStatsByDimension[];
+
+  @doc("Stats grouped by operation name")
+  @encodedName("application/json", "by_operation")
+  byOperation?: SpanStatsByDimension[];
+}
+
+@doc("Span statistics for a specific dimension value")
+model SpanStatsByDimension {
+  @doc("Dimension value (e.g., service name)")
+  dimension: string;
+
+  @doc("Span count for this dimension")
+  count: Count;
+
+  @doc("Average duration in nanoseconds")
+  @encodedName("application/json", "avg_duration_ns")
+  avgDurationNs: float64;
+
+  @doc("Error rate for this dimension")
+  @encodedName("application/json", "error_rate")
+  errorRate: Ratio;
+}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@ancplua/qyl-api-schema",
+  "version": "0.2.0",
+  "description": "TypeSpec source of truth for qyl API contracts. Emits OpenAPI, JSON Schema, Qyl.Api.Contracts DTOs, and TypeScript contract types; not an OpenTelemetry package, storage schema, or server implementation.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ANcpLua/qyl-api-schema.git"
+  },
+  "homepage": "https://github.com/ANcpLua/qyl-api-schema#readme",
+  "bugs": {
+    "url": "https://github.com/ANcpLua/qyl-api-schema/issues"
+  },
+  "keywords": [
+    "typespec",
+    "qyl",
+    "observability",
+    "contracts",
+    "openapi"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./index.tsp",
+    "./otel": "./otel/otel-conventions.tsp",
+    "./models/*": "./models/*.tsp",
+    "./models/agent/*": "./models/agent/*.tsp",
+    "./common/*": "./common/*.tsp",
+    "./api/*": "./api/*.tsp",
+    "./intelligence/*": "./intelligence/*.tsp",
+    "./intelligence/seed/*": "./intelligence/seed/*.tsp",
+    "./generated/otel-keys": "./generated/otel-keys.gen.tsp"
+  },
+  "files": [
+    "index.tsp",
+    "api/**/*.tsp",
+    "common/**/*.tsp",
+    "intelligence/**/*.tsp",
+    "models/**/*.tsp",
+    "otel/**/*.tsp",
+    "generated/**/*.tsp",
+    "generated/README.md",
+    "tspconfig.yaml",
+    "README.md",
+    "VERSIONING.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build:emitters": "tsc -p emitters/telemetry-control-graph && tsc -p emitters/csharp && tsc -p emitters/ts-types && tsc -p emitters/otelconventions-lint",
+    "prepare": "npm run build:emitters",
+    "compile": "npm run build:emitters && tsp compile main.tsp",
+    "watch": "tsp compile main.tsp --watch",
+    "format": "tsp format **/*.tsp",
+    "lint": "npm run build:emitters && tsp compile main.tsp --no-emit --warn-as-error",
+    "lint:public": "tsp compile index.tsp --no-emit --warn-as-error"
+  },
+  "peerDependencies": {
+    "@typespec/compiler": "^1.13.0 || >=1.13.0-dev.0"
+  },
+  "devDependencies": {
+    "@ancplua/typespec-emit-csharp": "file:./emitters/csharp",
+    "@ancplua/typespec-emit-ts-types": "file:./emitters/ts-types",
+    "@ancplua/typespec-otel-semconv": "1.41.0-2",
+    "@ancplua/typespec-otelconventions-lint": "file:./emitters/otelconventions-lint",
+    "@types/node": "25.9.4",
+    "@typespec/compiler": "1.13.0",
+    "@typespec/events": "0.83.0",
+    "@typespec/http": "1.13.0",
+    "@typespec/json-schema": "1.13.0",
+    "@typespec/openapi": "1.13.0",
+    "@typespec/openapi3": "1.13.0",
+    "@typespec/rest": "0.83.0",
+    "@typespec/sse": "0.83.0",
+    "@typespec/streams": "0.83.0",
+    "@typespec/versioning": "0.83.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.9",
+    "@qyl/telemetry-control-graph": "file:./emitters/telemetry-control-graph"
+  },
+  "dependencies": {
+    "@azure-tools/typespec-azure-core": "^0.69.0",
+    "@typespec/xml": "^0.83.0"
+  }
+}

package/tspconfig.yaml

@@ -0,0 +1,49 @@
+# qyl-api-schema TypeSpec configuration.
+# This repo is a contract source, not a server implementation. It emits schema
+# and DTO artifacts only; qyl owns runtime services and physical storage schemas.
+
+emit:
+  - "@qyl/telemetry-control-graph"
+  - "@ancplua/typespec-emit-csharp"
+  - "@ancplua/typespec-emit-ts-types"
+  - "@typespec/openapi3"
+  - "@typespec/json-schema"
+
+options:
+  "@qyl/telemetry-control-graph":
+    emitter-output-dir: "{project-root}/generated/control-graph"
+    file-types:
+      - json
+      - yaml
+    include-schema: true
+    include-conformance-plan: true
+    include-report: true
+
+  "@ancplua/typespec-emit-csharp":
+    emitter-output-dir: "{project-root}/generated/contracts"
+
+  "@ancplua/typespec-emit-ts-types":
+    emitter-output-dir: "{project-root}/generated/ts-types"
+
+  "@typespec/openapi3":
+    emitter-output-dir: "{project-root}/generated/openapi"
+    output-file: "qyl.openapi.json"
+    file-type: json
+    openapi-versions:
+      - "3.2.0"
+    omit-unreachable-types: true
+    operation-id-strategy: parent-container
+
+  "@typespec/json-schema":
+    emitter-output-dir: "{project-root}/generated/json-schema"
+    file-type: json
+    bundleId: qyl-api-schema
+
+linter:
+  extends:
+    - "@typespec/http/all"
+    - "@ancplua/typespec-otelconventions-lint/recommended"
+  enable:
+    "@ancplua/typespec-otelconventions-lint/graph-attribute-key":
+      pattern: "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
+      allowedRoots: ["qyl", "ancplua"]