@ancplua/qyl-api-schema 0.2.0

package/models/session.tsp

@@ -0,0 +1,274 @@
+// =============================================================================
+// ANcpLua v2.0 - Session Semantic Conventions (OTel v1.40)
+// =============================================================================
+// User session telemetry attributes.
+// =============================================================================
+
+import "@typespec/openapi";
+import "../common/types.tsp";
+
+using TypeSpec.OpenAPI;
+using Qyl.Api.Contracts.Common;
+
+namespace Qyl.Api.Contracts.Domains.Observe.Session;
+
+// =============================================================================
+// Session Attributes
+// =============================================================================
+
+@doc("Session span/event attributes")
+model SessionAttributes {
+  @doc("Session ID")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Session.Id)
+  id: SessionId;
+
+  @doc("Previous session ID (for session continuity)")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Session.PreviousId)
+  previousId?: SessionId;
+}
+
+// =============================================================================
+// Session Event Models
+// =============================================================================
+
+@doc("Session lifecycle event")
+model SessionEvent {
+  @doc("Event name")
+  @encodedName("application/json", "event.name")
+  eventName: SessionEventName;
+
+  @doc("Session ID")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Session.Id)
+  sessionId: SessionId;
+
+  @doc("Event timestamp")
+  timestamp: utcDateTime;
+
+  @doc("Event domain")
+  @encodedName("application/json", "event.domain")
+  eventDomain: "session";
+}
+
+@doc("Session event names")
+enum SessionEventName {
+  @doc("Session started")
+  sessionStart: "session.start",
+
+  @doc("Session ended")
+  sessionEnd: "session.end",
+}
+
+// =============================================================================
+// Session Entity Model (Full Session Record)
+// =============================================================================
+
+@doc("Complete session entity with aggregated data")
+@TypeSpec.OpenAPI.extension("x-csharp-type", "SessionEntity")
+model SessionEntity {
+  @doc("Session ID")
+  @key
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Session.Id)
+  sessionId: SessionId;
+
+  @doc("User ID (if authenticated)")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.User.Id)
+  userId?: UserId;
+
+  @doc("Session start time")
+  @encodedName("application/json", "start_time")
+  startTime: utcDateTime;
+
+  @doc("Session end time")
+  @encodedName("application/json", "end_time")
+  endTime?: utcDateTime;
+
+  @doc("Session duration in milliseconds")
+  @encodedName("application/json", "duration_ms")
+  durationMs?: DurationMs;
+
+  @doc("Total trace count in session")
+  @encodedName("application/json", "trace_count")
+  @minValue(0)
+  traceCount: int32;
+
+  @doc("Total span count in session")
+  @encodedName("application/json", "span_count")
+  @minValue(0)
+  spanCount: int32;
+
+  @doc("Total error count in session")
+  @encodedName("application/json", "error_count")
+  @minValue(0)
+  errorCount: int32;
+
+  @doc("Service names observed in this session")
+  services: string[];
+
+  @doc("Session state")
+  state: SessionState;
+
+  @doc("Client information")
+  client?: SessionClientInfo;
+
+  @doc("Location information")
+  geo?: SessionGeoInfo;
+
+  @doc("GenAI usage summary")
+  @encodedName("application/json", "genai_usage")
+  genaiUsage?: SessionGenAiUsage;
+}
+
+@doc("Session states")
+enum SessionState {
+  @doc("Session is active")
+  active: "active",
+
+  @doc("Session is idle")
+  idle: "idle",
+
+  @doc("Session has ended normally")
+  ended: "ended",
+
+  @doc("Session has timed out")
+  timedOut: "timed_out",
+
+  @doc("Session was invalidated")
+  invalidated: "invalidated",
+}
+
+@doc("Session client information")
+model SessionClientInfo {
+  @doc("Client IP address")
+  ip?: IpAddress;
+
+  @doc("User agent string")
+  @encodedName("application/json", "user_agent")
+  userAgent?: UserAgent;
+
+  @doc("Device type")
+  @encodedName("application/json", "device_type")
+  deviceType?: DeviceType;
+
+  @doc("Operating system")
+  os?: string;
+
+  @doc("Browser name")
+  browser?: string;
+
+  @doc("Browser version")
+  @encodedName("application/json", "browser_version")
+  browserVersion?: string;
+}
+
+@doc("Device types")
+enum DeviceType {
+  @doc("Desktop computer")
+  desktop: "desktop",
+
+  @doc("Mobile phone")
+  mobile: "mobile",
+
+  @doc("Tablet device")
+  tablet: "tablet",
+
+  @doc("TV or set-top box")
+  tv: "tv",
+
+  @doc("Gaming console")
+  console: "console",
+
+  @doc("Wearable device")
+  wearable: "wearable",
+
+  @doc("IoT device")
+  iot: "iot",
+
+  @doc("Bot/crawler")
+  bot: "bot",
+
+  @doc("Unknown device")
+  `unknown`: "unknown",
+}
+
+@doc("Session geographic information")
+model SessionGeoInfo {
+  @doc("Country code (ISO 3166-1 alpha-2)")
+  @encodedName("application/json", "country_code")
+  countryCode?: string;
+
+  @doc("Country name")
+  @encodedName("application/json", "country_name")
+  countryName?: string;
+
+  @doc("Region/state")
+  region?: string;
+
+  @doc("City")
+  city?: string;
+
+  @doc("Postal code")
+  @encodedName("application/json", "postal_code")
+  postalCode?: string;
+
+  @doc("Timezone")
+  timezone?: string;
+}
+
+@doc("Session GenAI usage summary")
+model SessionGenAiUsage {
+  @doc("Total GenAI requests in session")
+  @encodedName("application/json", "request_count")
+  @minValue(0)
+  requestCount: int32;
+
+  @doc("Total input tokens consumed")
+  @encodedName("application/json", "total_input_tokens")
+  totalInputTokens: TokenCount;
+
+  @doc("Total output tokens generated")
+  @encodedName("application/json", "total_output_tokens")
+  totalOutputTokens: TokenCount;
+
+  @doc("Models used in session")
+  @encodedName("application/json", "models_used")
+  modelsUsed: string[];
+
+  @doc("Providers used in session")
+  @encodedName("application/json", "providers_used")
+  providersUsed: string[];
+
+  @doc("Estimated cost in USD")
+  @encodedName("application/json", "estimated_cost_usd")
+  estimatedCostUsd?: float64;
+}
+
+// =============================================================================
+// Session Statistics
+// =============================================================================
+
+@doc("Aggregated session statistics")
+model SessionStats {
+  @doc("Active sessions count")
+  @encodedName("application/json", "active_sessions")
+  activeSessions: Count;
+
+  @doc("Total sessions in time range")
+  @encodedName("application/json", "total_sessions")
+  totalSessions: Count;
+
+  @doc("Average session duration in milliseconds")
+  @encodedName("application/json", "avg_duration_ms")
+  avgDurationMs: float64;
+
+  @doc("Sessions with errors")
+  @encodedName("application/json", "sessions_with_errors")
+  sessionsWithErrors: Count;
+
+  @doc("Sessions with GenAI usage")
+  @encodedName("application/json", "sessions_with_genai")
+  sessionsWithGenAi: Count;
+
+  @doc("Bounce rate (single-page sessions)")
+  @encodedName("application/json", "bounce_rate")
+  bounceRate: Ratio;
+}

package/models/system.tsp

@@ -0,0 +1,400 @@
+// =============================================================================
+// ANcpLua v2.0 - System Semantic Conventions (OTel v1.40)
+// =============================================================================
+// Operating system telemetry attributes.
+// =============================================================================
+
+import "../common/types.tsp";
+import "../otel/resource.tsp";
+
+using Qyl.Api.Contracts.Common;
+using Qyl.Api.Contracts.OTel.Resource;
+
+namespace Qyl.Api.Contracts.Domains.Runtime.System;
+
+// =============================================================================
+// OS Resource Attributes
+// =============================================================================
+
+@doc("Operating system resource attributes")
+model OsAttributes {
+  @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)
+  description?: string;
+
+  @doc("Operating system name")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Os.Name)
+  name?: string;
+
+  @doc("Operating system version")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Os.Version)
+  version?: string;
+
+  @doc("Operating system build ID")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Os.BuildId)
+  buildId?: string;
+}
+
+// =============================================================================
+// System Metrics
+// =============================================================================
+
+@doc("System CPU utilization metric")
+model SystemCpuUtilizationMetric {
+  @doc("Metric name")
+  name: "system.cpu.utilization";
+
+  @doc("Metric unit (ratio)")
+  unit: "1";
+
+  @doc("CPU state")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.System.CpuState)
+  cpuState: SystemCpuState;
+
+  @doc("CPU logical number")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.System.CpuLogicalNumber)
+  cpuLogicalNumber?: int32;
+}
+
+@doc("System CPU time metric")
+model SystemCpuTimeMetric {
+  @doc("Metric name")
+  name: "system.cpu.time";
+
+  @doc("Metric unit (seconds)")
+  unit: "s";
+
+  @doc("CPU state")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.System.CpuState)
+  cpuState: SystemCpuState;
+
+  @doc("CPU logical number")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.System.CpuLogicalNumber)
+  cpuLogicalNumber?: int32;
+}
+
+@doc("System CPU frequency metric")
+model SystemCpuFrequencyMetric {
+  @doc("Metric name")
+  name: "system.cpu.frequency";
+
+  @doc("Metric unit (Hz)")
+  unit: "Hz";
+
+  @doc("CPU logical number")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.System.CpuLogicalNumber)
+  cpuLogicalNumber?: int32;
+}
+
+@doc("System memory usage metric")
+model SystemMemoryUsageMetric {
+  @doc("Metric name")
+  name: "system.memory.usage";
+
+  @doc("Metric unit (bytes)")
+  unit: "By";
+
+  @doc("Memory state")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.System.MemoryState)
+  memoryState: SystemMemoryState;
+}
+
+@doc("System memory utilization metric")
+model SystemMemoryUtilizationMetric {
+  @doc("Metric name")
+  name: "system.memory.utilization";
+
+  @doc("Metric unit (ratio)")
+  unit: "1";
+
+  @doc("Memory state")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.System.MemoryState)
+  memoryState: SystemMemoryState;
+}
+
+@doc("System disk IO metric")
+model SystemDiskIoMetric {
+  @doc("Metric name")
+  name: "system.disk.io";
+
+  @doc("Metric unit (bytes)")
+  unit: "By";
+
+  @doc("Disk device")
+  @encodedName("application/json", "system.disk.device")
+  diskDevice: string;
+
+  @doc("IO direction")
+  @encodedName("application/json", "system.disk.direction")
+  diskDirection: string;
+}
+
+@doc("System disk operations metric")
+model SystemDiskOperationsMetric {
+  @doc("Metric name")
+  name: "system.disk.operations";
+
+  @doc("Metric unit")
+  unit: "{operation}";
+
+  @doc("Disk device")
+  @encodedName("application/json", "system.disk.device")
+  diskDevice: string;
+
+  @doc("IO direction")
+  @encodedName("application/json", "system.disk.direction")
+  diskDirection: string;
+}
+
+@doc("System disk IO time metric")
+model SystemDiskIoTimeMetric {
+  @doc("Metric name")
+  name: "system.disk.io_time";
+
+  @doc("Metric unit (seconds)")
+  unit: "s";
+
+  @doc("Disk device")
+  @encodedName("application/json", "system.disk.device")
+  diskDevice: string;
+}
+
+@doc("System filesystem usage metric")
+model SystemFilesystemUsageMetric {
+  @doc("Metric name")
+  name: "system.filesystem.usage";
+
+  @doc("Metric unit (bytes)")
+  unit: "By";
+
+  @doc("Filesystem device")
+  @encodedName("application/json", "system.filesystem.device")
+  device: string;
+
+  @doc("Filesystem mount point")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.System.FilesystemMountpoint)
+  mountpoint: string;
+
+  @doc("Filesystem type")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.System.FilesystemType)
+  fsType: string;
+
+  @doc("Filesystem state")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.System.FilesystemState)
+  state: SystemFilesystemState;
+}
+
+@doc("System network IO metric")
+model SystemNetworkIoMetric {
+  @doc("Metric name")
+  name: "system.network.io";
+
+  @doc("Metric unit (bytes)")
+  unit: "By";
+
+  @doc("Network device")
+  @encodedName("application/json", "system.network.device")
+  networkDevice: string;
+
+  @doc("IO direction")
+  @encodedName("application/json", "system.network.direction")
+  networkDirection: string;
+}
+
+@doc("System network connections metric")
+model SystemNetworkConnectionsMetric {
+  @doc("Metric name")
+  name: "system.network.connections";
+
+  @doc("Metric unit")
+  unit: "{connection}";
+
+  @doc("Network protocol")
+  @encodedName("application/json", "system.network.protocol")
+  protocol: string;
+
+  @doc("Network state")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Network.ConnectionState)
+  state: SystemNetworkState;
+}
+
+@doc("System paging usage metric")
+model SystemPagingUsageMetric {
+  @doc("Metric name")
+  name: "system.paging.usage";
+
+  @doc("Metric unit (bytes)")
+  unit: "By";
+
+  @doc("Paging state")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.System.PagingState)
+  pagingState: SystemPagingState;
+
+  @doc("Paging device")
+  @encodedName("application/json", "system.paging.device")
+  device?: string;
+}
+
+@doc("System paging operations metric")
+model SystemPagingOperationsMetric {
+  @doc("Metric name")
+  name: "system.paging.operations";
+
+  @doc("Metric unit")
+  unit: "{operation}";
+
+  @doc("Paging type")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.System.PagingType)
+  pagingType: SystemPagingType;
+
+  @doc("Paging direction")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.System.PagingDirection)
+  pagingDirection: string;
+}
+
+@doc("System process count metric")
+model SystemProcessCountMetric {
+  @doc("Metric name")
+  name: "system.process.count";
+
+  @doc("Metric unit")
+  unit: "{process}";
+
+  @doc("Process status")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.System.ProcessStatus)
+  processStatus: SystemProcessStatus;
+}
+
+// =============================================================================
+// System Enumerations
+// =============================================================================
+
+@doc("System CPU states")
+enum SystemCpuState {
+  @doc("User mode")
+  user: "user",
+
+  @doc("System mode")
+  system: "system",
+
+  @doc("Nice mode")
+  nice: "nice",
+
+  @doc("Idle")
+  idle: "idle",
+
+  @doc("I/O wait")
+  iowait: "iowait",
+
+  @doc("Interrupt")
+  interrupt: "interrupt",
+
+  @doc("Steal")
+  steal: "steal",
+}
+
+@doc("System memory states")
+enum SystemMemoryState {
+  @doc("Used memory")
+  used: "used",
+
+  @doc("Free memory")
+  free: "free",
+
+  @doc("Buffered memory")
+  buffered: "buffered",
+
+  @doc("Cached memory")
+  cached: "cached",
+
+  @doc("Shared memory")
+  shared: "shared",
+}
+
+@doc("System filesystem states")
+enum SystemFilesystemState {
+  @doc("Used space")
+  used: "used",
+
+  @doc("Free space")
+  free: "free",
+
+  @doc("Reserved space")
+  reserved: "reserved",
+}
+
+@doc("System network states")
+enum SystemNetworkState {
+  @doc("CLOSE state")
+  close: "close",
+
+  @doc("CLOSE_WAIT state")
+  closeWait: "close_wait",
+
+  @doc("CLOSING state")
+  closing: "closing",
+
+  @doc("DELETE state")
+  delete: "delete",
+
+  @doc("ESTABLISHED state")
+  established: "established",
+
+  @doc("FIN_WAIT_1 state")
+  finWait1: "fin_wait_1",
+
+  @doc("FIN_WAIT_2 state")
+  finWait2: "fin_wait_2",
+
+  @doc("LAST_ACK state")
+  lastAck: "last_ack",
+
+  @doc("LISTEN state")
+  listen: "listen",
+
+  @doc("SYN_RECV state")
+  synRecv: "syn_recv",
+
+  @doc("SYN_SENT state")
+  synSent: "syn_sent",
+
+  @doc("TIME_WAIT state")
+  timeWait: "time_wait",
+}
+
+@doc("System paging states")
+enum SystemPagingState {
+  @doc("Used")
+  used: "used",
+
+  @doc("Free")
+  free: "free",
+}
+
+@doc("System paging types")
+enum SystemPagingType {
+  @doc("Major page fault")
+  major: "major",
+
+  @doc("Minor page fault")
+  minor: "minor",
+}
+
+@doc("System process status")
+enum SystemProcessStatus {
+  @doc("Running")
+  running: "running",
+
+  @doc("Sleeping")
+  sleeping: "sleeping",
+
+  @doc("Stopped")
+  stopped: "stopped",
+
+  @doc("Defunct/zombie")
+  defunct: "defunct",
+}