@ancplua/qyl-api-schema 0.2.0

package/otel/metrics.tsp

@@ -0,0 +1,358 @@
+// =============================================================================
+// ANcpLua v2.0 - OpenTelemetry Metrics Model
+// =============================================================================
+// Metrics data model with discriminated unions for different metric types.
+// =============================================================================
+
+import "@typespec/http";
+import "../common/types.tsp";
+import "./enums.tsp";
+import "./resource.tsp";
+
+using TypeSpec.Http;
+using Qyl.Api.Contracts.Common;
+using Qyl.Api.Contracts.OTel.Enums;
+using Qyl.Api.Contracts.OTel.Resource;
+
+namespace Qyl.Api.Contracts.OTel.Metrics;
+
+// =============================================================================
+// Metric Model
+// =============================================================================
+
+@doc("OpenTelemetry Metric containing measurement data")
+model Metric {
+  @doc("Metric name (e.g., http.server.request.duration)")
+  @minLength(1)
+  name: string;
+
+  @doc("Metric description")
+  description?: string;
+
+  @doc("Metric unit (e.g., 's', 'By', '1')")
+  unit?: string;
+
+  @doc("Metric data (discriminated by type)")
+  data: MetricData;
+
+  @doc("Metric metadata attributes")
+  metadata?: Attribute[];
+
+  @doc("Resource describing the entity that produced this metric")
+  resource: Qyl.Api.Contracts.OTel.Resource.Resource;
+
+  @doc("Instrumentation scope")
+  @encodedName("application/json", "instrumentation_scope")
+  instrumentationScope?: InstrumentationScope;
+}
+
+// =============================================================================
+// Metric Data Types (Discriminated Union)
+// =============================================================================
+
+@doc("Metric data discriminated by type")
+@discriminator("type")
+model MetricData {
+  @doc("Metric type discriminator")
+  type: MetricType;
+}
+
+@doc("Gauge metric - instantaneous value at a point in time")
+model GaugeData extends MetricData {
+  /** Discriminator identifying this as gauge metric data */
+  type: MetricType.gauge;
+
+  @doc("Gauge data points")
+  @encodedName("application/json", "data_points")
+  dataPoints: NumberDataPoint[];
+}
+
+@doc("Sum metric - cumulative or delta counter")
+model SumData extends MetricData {
+  /** Discriminator identifying this as sum metric data */
+  type: MetricType.sum;
+
+  @doc("Sum data points")
+  @encodedName("application/json", "data_points")
+  dataPoints: NumberDataPoint[];
+
+  @doc("Whether the sum is monotonically increasing")
+  @encodedName("application/json", "is_monotonic")
+  isMonotonic: boolean;
+
+  @doc("Aggregation temporality")
+  @encodedName("application/json", "aggregation_temporality")
+  aggregationTemporality: AggregationTemporality;
+}
+
+@doc("Histogram metric - distribution of values in buckets")
+model HistogramData extends MetricData {
+  /** Discriminator identifying this as histogram metric data */
+  type: MetricType.histogram;
+
+  @doc("Histogram data points")
+  @encodedName("application/json", "data_points")
+  dataPoints: HistogramDataPoint[];
+
+  @doc("Aggregation temporality")
+  @encodedName("application/json", "aggregation_temporality")
+  aggregationTemporality: AggregationTemporality;
+}
+
+@doc("Exponential histogram metric - distribution with exponential bucket boundaries")
+model ExponentialHistogramData extends MetricData {
+  /** Discriminator identifying this as exponential histogram metric data */
+  type: MetricType.exponentialHistogram;
+
+  @doc("Exponential histogram data points")
+  @encodedName("application/json", "data_points")
+  dataPoints: ExponentialHistogramDataPoint[];
+
+  @doc("Aggregation temporality")
+  @encodedName("application/json", "aggregation_temporality")
+  aggregationTemporality: AggregationTemporality;
+}
+
+@doc("Summary metric - pre-aggregated quantile distribution")
+model SummaryData extends MetricData {
+  /** Discriminator identifying this as summary metric data */
+  type: MetricType.summary;
+
+  @doc("Summary data points")
+  @encodedName("application/json", "data_points")
+  dataPoints: SummaryDataPoint[];
+}
+
+// =============================================================================
+// Data Point Models
+// =============================================================================
+
+@doc("Base data point with common fields")
+model DataPointBase {
+  @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", "time_unix_nano")
+  timeUnixNano: UnixNanos;
+
+  @doc("Data point attributes")
+  attributes?: Attribute[];
+
+  @doc("Data point flags")
+  flags?: DataPointFlags;
+}
+
+@doc("Numeric data point (for Gauge and Sum)")
+model NumberDataPoint extends DataPointBase {
+  @doc("Value as integer")
+  @encodedName("application/json", "as_int")
+  asInt?: int64;
+
+  @doc("Value as double")
+  @encodedName("application/json", "as_double")
+  asDouble?: float64;
+
+  @doc("Exemplars for the data point")
+  exemplars?: Exemplar[];
+}
+
+@doc("Histogram data point")
+model HistogramDataPoint extends DataPointBase {
+  @doc("Number of values in the histogram")
+  count: int64;
+
+  @doc("Sum of all values")
+  sum?: float64;
+
+  @doc("Bucket counts")
+  @encodedName("application/json", "bucket_counts")
+  bucketCounts: int64[];
+
+  @doc("Explicit bucket boundaries")
+  @encodedName("application/json", "explicit_bounds")
+  explicitBounds: float64[];
+
+  @doc("Minimum value")
+  min?: float64;
+
+  @doc("Maximum value")
+  max?: float64;
+
+  @doc("Exemplars for the data point")
+  exemplars?: Exemplar[];
+}
+
+@doc("Exponential histogram data point")
+model ExponentialHistogramDataPoint extends DataPointBase {
+  @doc("Number of values")
+  count: int64;
+
+  @doc("Sum of all values")
+  sum?: float64;
+
+  @doc("Scale factor for bucket boundaries")
+  scale: int32;
+
+  @doc("Zero count")
+  @encodedName("application/json", "zero_count")
+  zeroCount: int64;
+
+  @doc("Zero threshold")
+  @encodedName("application/json", "zero_threshold")
+  zeroThreshold?: float64;
+
+  @doc("Positive bucket counts")
+  positive: ExponentialBuckets;
+
+  @doc("Negative bucket counts")
+  negative: ExponentialBuckets;
+
+  @doc("Minimum value")
+  min?: float64;
+
+  @doc("Maximum value")
+  max?: float64;
+
+  @doc("Exemplars for the data point")
+  exemplars?: Exemplar[];
+}
+
+@doc("Exponential histogram buckets")
+model ExponentialBuckets {
+  @doc("Offset of the first bucket")
+  offset: int32;
+
+  @doc("Bucket counts")
+  @encodedName("application/json", "bucket_counts")
+  bucketCounts: int64[];
+}
+
+@doc("Summary data point")
+model SummaryDataPoint extends DataPointBase {
+  @doc("Number of values")
+  count: int64;
+
+  @doc("Sum of all values")
+  sum: float64;
+
+  @doc("Quantile values")
+  @encodedName("application/json", "quantile_values")
+  quantileValues: QuantileValue[];
+}
+
+@doc("Quantile value for summary")
+model QuantileValue {
+  @doc("Quantile (0.0 to 1.0)")
+  @minValue(0.0)
+  @maxValue(1.0)
+  quantile: float64;
+
+  @doc("Value at this quantile")
+  value: float64;
+}
+
+@doc("Exemplar - sample trace linked to metric")
+model Exemplar {
+  @doc("Timestamp in nanoseconds since epoch")
+  @encodedName("application/json", "time_unix_nano")
+  timeUnixNano: UnixNanos;
+
+  @doc("Value as integer")
+  @encodedName("application/json", "as_int")
+  asInt?: int64;
+
+  @doc("Value as double")
+  @encodedName("application/json", "as_double")
+  asDouble?: float64;
+
+  @doc("Span ID of the exemplar")
+  @encodedName("application/json", "span_id")
+  spanId?: SpanId;
+
+  @doc("Trace ID of the exemplar")
+  @encodedName("application/json", "trace_id")
+  traceId?: TraceId;
+
+  @doc("Filtered attributes")
+  @encodedName("application/json", "filtered_attributes")
+  filteredAttributes?: Attribute[];
+}
+
+// =============================================================================
+// Metric Query & Aggregation
+// =============================================================================
+
+@doc("Metric query filters")
+model MetricQueryFilters {
+  @doc("Filter by metric name (supports wildcards)")
+  @query
+  name?: string;
+
+  @doc("Filter by metric type")
+  @query
+  type?: MetricType;
+
+  @doc("Filter by service name")
+  @query
+  @encodedName("application/json", "service_name")
+  serviceName?: string;
+
+  @doc("Filter by attribute key-value pair")
+  @query
+  attribute?: string;
+
+  @doc("Aggregation function")
+  @query
+  @encodedName("application/json", "agg_func")
+  aggFunc?: AggregationFunction;
+}
+
+@doc("Aggregation functions for metrics")
+enum AggregationFunction {
+  @doc("Sum of values")
+  sum: "sum",
+
+  @doc("Average of values")
+  avg: "avg",
+
+  @doc("Minimum value")
+  min: "min",
+
+  @doc("Maximum value")
+  max: "max",
+
+  @doc("Count of values")
+  count: "count",
+
+  @doc("Latest value")
+  last: "last",
+
+  @doc("Rate of change per second")
+  rate: "rate",
+
+  @doc("Increase over time range")
+  increase: "increase",
+}
+
+@doc("Time series data for graphing")
+model TimeSeries {
+  @doc("Metric name")
+  metric: string;
+
+  @doc("Dimension labels")
+  labels: Attribute[];
+
+  @doc("Data points over time")
+  points: TimeSeriesPoint[];
+}
+
+@doc("Single point in a time series")
+model TimeSeriesPoint {
+  @doc("Timestamp")
+  timestamp: utcDateTime;
+
+  @doc("Value")
+  value: float64;
+}

package/otel/otel-conventions.tsp

@@ -0,0 +1,14 @@
+// =============================================================================
+// otel/otel-conventions.tsp — OTel core barrel
+// =============================================================================
+// Exposed via the public subpath `@ancplua/qyl-api-schema/otel` for
+// consumers that want only the OpenTelemetry-shaped signal models without the
+// rest of the qyl API surface.
+// =============================================================================
+
+import "./enums.tsp";
+import "./resource.tsp";
+import "./span.tsp";
+import "./logs.tsp";
+import "./metrics.tsp";
+import "./profiles.tsp";

package/otel/profiles.tsp

@@ -0,0 +1,335 @@
+// =============================================================================
+// ANcpLua v2.0 - OpenTelemetry Profiles Model (v1development)
+// =============================================================================
+// Continuous profiling signal following OTel Profiles proto specification.
+// Proto package: opentelemetry.proto.profiles.v1development
+// All attributes are Development stability (semconv v1.39.0-v1.40.0).
+// =============================================================================
+
+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.Profiles;
+
+// =============================================================================
+// Profile Model
+// =============================================================================
+
+@doc("OpenTelemetry Profile representing a continuous profiling snapshot")
+model Profile {
+  @doc("Unique profile identifier (16 hex chars)")
+  @key
+  @encodedName("application/json", "profile_id")
+  profileId: string;
+
+  @doc("Sample type describing what was measured")
+  @encodedName("application/json", "sample_type")
+  sampleType?: ProfileValueType;
+
+  @doc("Profiling samples")
+  samples?: ProfileSample[];
+
+  @doc("Profile start timestamp in nanoseconds since epoch")
+  @encodedName("application/json", "time_unix_nano")
+  timeUnixNano: UnixNanos;
+
+  @doc("Profile duration in nanoseconds")
+  @encodedName("application/json", "duration_nano")
+  durationNano: DurationNs;
+
+  @doc("Sampling period type")
+  @encodedName("application/json", "period_type")
+  periodType?: ProfileValueType;
+
+  @doc("Sampling period value")
+  period?: int64;
+
+  @doc("Original payload format (pprof, jfr, linux_perf)")
+  @encodedName("application/json", "original_payload_format")
+  originalPayloadFormat?: OriginalPayloadFormat;
+
+  @doc("Original payload bytes (base64 encoded, opaque — not parsed)")
+  @encodedName("application/json", "original_payload")
+  originalPayload?: bytes;
+
+  @doc("Profile attributes")
+  attributes?: Attribute[];
+
+  @doc("Dropped attributes count")
+  @encodedName("application/json", "dropped_attributes_count")
+  droppedAttributesCount?: Count;
+
+  @doc("Resource describing the entity that produced this profile")
+  resource: Qyl.Api.Contracts.OTel.Resource.Resource;
+
+  @doc("Instrumentation scope")
+  @encodedName("application/json", "instrumentation_scope")
+  instrumentationScope?: InstrumentationScope;
+
+  // Dictionary tables (dereferenced from ProfilesDictionary)
+
+  @doc("String table for index-based lookups")
+  @encodedName("application/json", "string_table")
+  stringTable?: string[];
+
+  @doc("Function table")
+  @encodedName("application/json", "function_table")
+  functionTable?: ProfileFunction[];
+
+  @doc("Location table")
+  @encodedName("application/json", "location_table")
+  locationTable?: ProfileLocation[];
+
+  @doc("Mapping table (memory-mapped binaries)")
+  @encodedName("application/json", "mapping_table")
+  mappingTable?: ProfileMapping[];
+
+  @doc("Link table for cross-signal correlation")
+  @encodedName("application/json", "link_table")
+  linkTable?: ProfileLink[];
+
+  @doc("Stack table (ordered location sequences)")
+  @encodedName("application/json", "stack_table")
+  stackTable?: ProfileStack[];
+}
+
+// =============================================================================
+// Profile Sub-Models
+// =============================================================================
+
+@doc("Sample type descriptor (what was measured and in what unit)")
+model ProfileValueType {
+  @doc("Type string index into string table")
+  @encodedName("application/json", "type_strindex")
+  typeStrindex?: int32;
+
+  @doc("Unit string index into string table")
+  @encodedName("application/json", "unit_strindex")
+  unitStrindex?: int32;
+}
+
+@doc("Individual profiling sample")
+model ProfileSample {
+  @doc("Stack index into stack table")
+  @encodedName("application/json", "stack_index")
+  stackIndex?: int32;
+
+  @doc("Attribute indices into attribute table")
+  @encodedName("application/json", "attribute_indices")
+  attributeIndices?: int32[];
+
+  @doc("Link index into link table for cross-signal correlation")
+  @encodedName("application/json", "link_index")
+  linkIndex?: int32;
+
+  @doc("Sample values (one per sample type)")
+  values?: int64[];
+
+  @doc("Timestamps for each value in nanoseconds since epoch")
+  @encodedName("application/json", "timestamps_unix_nano")
+  timestampsUnixNano?: UnixNanos[];
+}
+
+@doc("Code location within a profiled binary")
+model ProfileLocation {
+  @doc("Mapping index into mapping table")
+  @encodedName("application/json", "mapping_index")
+  mappingIndex?: int32;
+
+  @doc("Instruction address (program counter)")
+  address?: uint64;
+
+  @doc("Source lines at this location")
+  lines?: ProfileLine[];
+
+  @doc("Attribute indices")
+  @encodedName("application/json", "attribute_indices")
+  attributeIndices?: int32[];
+}
+
+@doc("Source line within a location")
+model ProfileLine {
+  @doc("Function index into function table")
+  @encodedName("application/json", "function_index")
+  functionIndex?: int32;
+
+  @doc("Source line number")
+  line?: int64;
+
+  @doc("Source column number")
+  column?: int64;
+}
+
+@doc("Function identity in a profiled binary")
+model ProfileFunction {
+  @doc("Function name string index")
+  @encodedName("application/json", "name_strindex")
+  nameStrindex?: int32;
+
+  @doc("System/mangled function name string index")
+  @encodedName("application/json", "system_name_strindex")
+  systemNameStrindex?: int32;
+
+  @doc("Source filename string index")
+  @encodedName("application/json", "filename_strindex")
+  filenameStrindex?: int32;
+
+  @doc("First line number of the function in source")
+  @encodedName("application/json", "start_line")
+  startLine?: int64;
+}
+
+@doc("Memory mapping for a loaded binary or shared library")
+model ProfileMapping {
+  @doc("Start address of the mapping in virtual memory")
+  @encodedName("application/json", "memory_start")
+  memoryStart?: uint64;
+
+  @doc("Limit address (exclusive) of the mapping")
+  @encodedName("application/json", "memory_limit")
+  memoryLimit?: uint64;
+
+  @doc("Offset within the mapped file")
+  @encodedName("application/json", "file_offset")
+  fileOffset?: uint64;
+
+  @doc("Filename string index of the mapped binary")
+  @encodedName("application/json", "filename_strindex")
+  filenameStrindex?: int32;
+
+  @doc("Attribute indices")
+  @encodedName("application/json", "attribute_indices")
+  attributeIndices?: int32[];
+}
+
+@doc("Cross-signal link from profile sample to trace/span")
+model ProfileLink {
+  @doc("Linked trace ID (16 bytes, W3C format)")
+  @encodedName("application/json", "trace_id")
+  traceId?: TraceId;
+
+  @doc("Linked span ID (8 bytes)")
+  @encodedName("application/json", "span_id")
+  spanId?: SpanId;
+}
+
+@doc("Ordered sequence of location indices forming a call stack")
+model ProfileStack {
+  @doc("Location indices from leaf (index 0) to root")
+  @encodedName("application/json", "location_indices")
+  locationIndices?: int32[];
+}
+
+// =============================================================================
+// Profile Query Filters
+// =============================================================================
+
+@doc("Filter parameters for querying profiles")
+model ProfileQueryFilters {
+  @doc("Filter by trace ID")
+  @query
+  @encodedName("application/json", "trace_id")
+  traceId?: TraceId;
+
+  @doc("Filter by span ID")
+  @query
+  @encodedName("application/json", "span_id")
+  spanId?: SpanId;
+
+  @doc("Filter by session ID")
+  @query
+  @encodedName("application/json", "session_id")
+  sessionId?: SessionId;
+
+  @doc("Filter by service name")
+  @query
+  @encodedName("application/json", "service_name")
+  serviceName?: string;
+
+  @doc("Filter by sample type (e.g., cpu, alloc_objects, wall)")
+  @query
+  @encodedName("application/json", "sample_type")
+  sampleType?: string;
+
+  @doc("Filter by profile frame type (e.g., dotnet, jvm, cpython)")
+  @query
+  @encodedName("application/json", "profile_frame_type")
+  profileFrameType?: string;
+
+  @doc("Filter by original payload format")
+  @query
+  @encodedName("application/json", "original_payload_format")
+  originalPayloadFormat?: OriginalPayloadFormat;
+
+  @doc("Minimum duration in nanoseconds")
+  @query
+  @encodedName("application/json", "min_duration_nano")
+  minDurationNano?: DurationNs;
+
+  @doc("Start of time range (inclusive, ISO 8601)")
+  @query
+  @encodedName("application/json", "time_from")
+  timeFrom?: utcDateTime;
+
+  @doc("End of time range (exclusive, ISO 8601)")
+  @query
+  @encodedName("application/json", "time_to")
+  timeTo?: utcDateTime;
+}
+
+// =============================================================================
+// Profile Aggregations
+// =============================================================================
+
+@doc("Aggregated profile statistics")
+model ProfileStats {
+  @doc("Total profile count")
+  @encodedName("application/json", "total_count")
+  totalCount: Count;
+
+  @doc("Total sample count across all profiles")
+  @encodedName("application/json", "total_sample_count")
+  totalSampleCount: Count;
+
+  @doc("Average duration in nanoseconds")
+  @encodedName("application/json", "avg_duration_nano")
+  avgDurationNano: float64;
+
+  @doc("Stats grouped by sample type")
+  @encodedName("application/json", "by_sample_type")
+  bySampleType?: ProfileStatsByDimension[];
+
+  @doc("Stats grouped by service")
+  @encodedName("application/json", "by_service")
+  byService?: ProfileStatsByDimension[];
+
+  @doc("Stats grouped by frame type")
+  @encodedName("application/json", "by_frame_type")
+  byFrameType?: ProfileStatsByDimension[];
+}
+
+@doc("Profile statistics for a specific dimension value")
+model ProfileStatsByDimension {
+  @doc("Dimension value")
+  dimension: string;
+
+  @doc("Profile count for this dimension")
+  count: Count;
+
+  @doc("Total sample count for this dimension")
+  @encodedName("application/json", "sample_count")
+  sampleCount: Count;
+
+  @doc("Average duration in nanoseconds")
+  @encodedName("application/json", "avg_duration_nano")
+  avgDurationNano: float64;
+}