@intentius/chant-lexicon-otel 0.81.0

package/src/components/common.ts

@@ -0,0 +1,151 @@
+/**
+ * Settings shared by many collector components (the collector's `config*`
+ * packages: configtls, configgrpc, confighttp, configretry, exporterhelper).
+ * Keys use the collector's own snake_case spelling, since they are emitted
+ * unchanged.
+ */
+
+/** A duration string the collector parses, e.g. `5s`, `250ms`, `1m30s`. */
+export type Duration = string;
+
+export interface TLSClientSettings {
+  insecure?: boolean;
+  insecure_skip_verify?: boolean;
+  ca_file?: string;
+  ca_pem?: string;
+  cert_file?: string;
+  cert_pem?: string;
+  key_file?: string;
+  key_pem?: string;
+  server_name_override?: string;
+  min_version?: string;
+  max_version?: string;
+  reload_interval?: Duration;
+  include_system_ca_certs_pool?: boolean;
+}
+
+export interface TLSServerSettings {
+  ca_file?: string;
+  cert_file?: string;
+  key_file?: string;
+  client_ca_file?: string;
+  client_ca_file_reload?: boolean;
+  min_version?: string;
+  max_version?: string;
+  reload_interval?: Duration;
+}
+
+/** An `auth` block naming an authenticator extension by id. */
+export interface AuthSettings {
+  authenticator: string;
+}
+
+export interface KeepaliveServerSettings {
+  server_parameters?: {
+    max_connection_idle?: Duration;
+    max_connection_age?: Duration;
+    max_connection_age_grace?: Duration;
+    time?: Duration;
+    timeout?: Duration;
+  };
+  enforcement_policy?: { min_time?: Duration; permit_without_stream?: boolean };
+}
+
+export interface GRPCServerSettings {
+  endpoint?: string;
+  transport?: "tcp" | "tcp4" | "tcp6" | "udp" | "unix";
+  tls?: TLSServerSettings;
+  max_recv_msg_size_mib?: number;
+  max_concurrent_streams?: number;
+  read_buffer_size?: number;
+  write_buffer_size?: number;
+  keepalive?: KeepaliveServerSettings;
+  auth?: AuthSettings;
+  include_metadata?: boolean;
+}
+
+export interface CORSSettings {
+  allowed_origins?: string[];
+  allowed_headers?: string[];
+  max_age?: number;
+}
+
+export interface HTTPServerSettings {
+  endpoint?: string;
+  tls?: TLSServerSettings;
+  cors?: CORSSettings;
+  auth?: AuthSettings;
+  max_request_body_size?: number;
+  include_metadata?: boolean;
+  response_headers?: Record<string, string>;
+}
+
+export type Compression = "gzip" | "zstd" | "snappy" | "zlib" | "deflate" | "lz4" | "none" | "";
+
+export interface GRPCClientSettings {
+  endpoint: string;
+  compression?: Compression;
+  tls?: TLSClientSettings;
+  headers?: Record<string, string>;
+  keepalive?: { time?: Duration; timeout?: Duration; permit_without_stream?: boolean };
+  read_buffer_size?: number;
+  write_buffer_size?: number;
+  wait_for_ready?: boolean;
+  balancer_name?: "pick_first" | "round_robin";
+  authority?: string;
+  auth?: AuthSettings;
+}
+
+export interface HTTPClientSettings {
+  endpoint?: string;
+  proxy_url?: string;
+  tls?: TLSClientSettings;
+  headers?: Record<string, string>;
+  timeout?: Duration;
+  compression?: Compression;
+  read_buffer_size?: number;
+  write_buffer_size?: number;
+  max_idle_conns?: number;
+  max_idle_conns_per_host?: number;
+  max_conns_per_host?: number;
+  idle_conn_timeout?: Duration;
+  disable_keep_alives?: boolean;
+  auth?: AuthSettings;
+}
+
+export interface RetrySettings {
+  enabled?: boolean;
+  initial_interval?: Duration;
+  randomization_factor?: number;
+  multiplier?: number;
+  max_interval?: Duration;
+  max_elapsed_time?: Duration;
+}
+
+export interface QueueSettings {
+  enabled?: boolean;
+  num_consumers?: number;
+  queue_size?: number;
+  /** The id of a storage extension, for a persistent queue. */
+  storage?: string;
+  blocking?: boolean;
+  sizer?: "requests" | "items" | "bytes";
+}
+
+/** `exporterhelper` settings every queued exporter accepts. */
+export interface ExporterHelperSettings {
+  timeout?: Duration;
+  retry_on_failure?: RetrySettings;
+  sending_queue?: QueueSettings;
+}
+
+/** One action in the `attributes` and `resource` processors. */
+export interface AttributeAction {
+  key?: string;
+  action: "insert" | "update" | "upsert" | "delete" | "hash" | "extract" | "convert";
+  value?: string | number | boolean;
+  pattern?: string;
+  from_attribute?: string;
+  from_context?: string;
+  converted_type?: "int" | "double" | "string";
+}

package/src/components/exporters.ts

@@ -0,0 +1,141 @@
+/**
+ * Built-in exporters: otlp, otlphttp, debug, prometheus, googlecloud.
+ */
+
+import { defineBuiltin } from "../define";
+import type { Duration, ExporterHelperSettings, GRPCClientSettings, HTTPClientSettings, TLSServerSettings } from "./common";
+
+// ── otlp ─────────────────────────────────────────────────────────────
+
+export type OtlpExporterConfig = GRPCClientSettings & ExporterHelperSettings;
+
+/** Sends OTLP over gRPC to another collector or a backend. */
+export const OtlpExporter = defineBuiltin<OtlpExporterConfig, "exporter", "otlp">({
+  kind: "exporter",
+  type: "otlp",
+  description: "Sends traces, metrics and logs over OTLP gRPC",
+  validate: (c) => (c.endpoint ? [] : ["endpoint is empty"]),
+  endpoints: (c) => (c.endpoint ? [c.endpoint] : []),
+});
+
+// ── otlphttp ─────────────────────────────────────────────────────────
+
+export type OtlpHttpExporterConfig = HTTPClientSettings &
+  ExporterHelperSettings & {
+    traces_endpoint?: string;
+    metrics_endpoint?: string;
+    logs_endpoint?: string;
+    encoding?: "proto" | "json";
+  };
+
+/** Sends OTLP over HTTP. `endpoint` gets `/v1/traces` etc. appended; the per-signal endpoints are used as given. */
+export const OtlpHttpExporter = defineBuiltin<OtlpHttpExporterConfig, "exporter", "otlphttp">({
+  kind: "exporter",
+  type: "otlphttp",
+  description: "Sends traces, metrics and logs over OTLP HTTP",
+  validate: (c) =>
+    c.endpoint || c.traces_endpoint || c.metrics_endpoint || c.logs_endpoint
+      ? []
+      : ["set endpoint, or at least one of traces_endpoint, metrics_endpoint and logs_endpoint"],
+  endpoints: (c) =>
+    [c.endpoint, c.traces_endpoint, c.metrics_endpoint, c.logs_endpoint].filter((e): e is string => typeof e === "string" && e !== ""),
+});
+
+// ── debug ────────────────────────────────────────────────────────────
+
+export interface DebugExporterConfig {
+  verbosity?: "basic" | "normal" | "detailed";
+  sampling_initial?: number;
+  sampling_thereafter?: number;
+  use_internal_logger?: boolean;
+}
+
+/** Writes telemetry to the collector's console, for debugging. */
+export const DebugExporter = defineBuiltin<DebugExporterConfig, "exporter", "debug">({
+  kind: "exporter",
+  type: "debug",
+  description: "Writes telemetry to the collector's console, for debugging",
+  endpoints: () => ["console"],
+});
+
+// ── prometheus ───────────────────────────────────────────────────────
+
+export interface PrometheusExporterConfig {
+  /** The address the exporter serves `/metrics` on, e.g. `0.0.0.0:8889`. */
+  endpoint: string;
+  namespace?: string;
+  const_labels?: Record<string, string>;
+  send_timestamps?: boolean;
+  metric_expiration?: Duration;
+  enable_open_metrics?: boolean;
+  add_metric_suffixes?: boolean;
+  resource_to_telemetry_conversion?: { enabled: boolean };
+  tls?: TLSServerSettings;
+}
+
+/** Serves metrics on an endpoint Prometheus scrapes. */
+export const PrometheusExporter = defineBuiltin<PrometheusExporterConfig, "exporter", "prometheus">({
+  kind: "exporter",
+  type: "prometheus",
+  description: "Serves metrics on an endpoint for Prometheus to scrape",
+  validate: (c) => (c.endpoint ? [] : ["endpoint is empty, so there is nothing to scrape"]),
+  endpoints: (c) => (c.endpoint ? [c.endpoint] : []),
+});
+
+// ── googlecloud ──────────────────────────────────────────────────────
+
+export interface GoogleCloudResourceFilter {
+  prefix?: string;
+  regex?: string;
+}
+
+export interface GoogleCloudExporterConfig extends ExporterHelperSettings {
+  /** The GCP project. Detected from credentials when omitted. */
+  project?: string;
+  user_agent?: string;
+  destination_project_quota?: boolean;
+  metric?: {
+    prefix?: string;
+    endpoint?: string;
+    use_insecure?: boolean;
+    known_domains?: string[];
+    skip_create_descriptor?: boolean;
+    instrumentation_library_labels?: boolean;
+    create_service_timeseries?: boolean;
+    create_metric_descriptor_buffer_size?: number;
+    service_resource_labels?: boolean;
+    resource_filters?: GoogleCloudResourceFilter[];
+    cumulative_normalization?: boolean;
+    sum_of_squared_deviation?: boolean;
+  };
+  trace?: {
+    endpoint?: string;
+    use_insecure?: boolean;
+    attribute_mappings?: Array<{ key: string; replacement: string }>;
+  };
+  log?: {
+    endpoint?: string;
+    use_insecure?: boolean;
+    default_log_name?: string;
+    resource_filters?: GoogleCloudResourceFilter[];
+    service_resource_labels?: boolean;
+    error_reporting_type?: boolean;
+  };
+}
+
+/**
+ * Sends traces to Cloud Trace, metrics to Cloud Monitoring and logs to Cloud
+ * Logging. With no endpoint overrides its topology endpoint is
+ * `googlecloud://projects/<project>`, naming where the data lands.
+ */
+export const GoogleCloudExporter = defineBuiltin<GoogleCloudExporterConfig, "exporter", "googlecloud">({
+  kind: "exporter",
+  type: "googlecloud",
+  description: "Sends traces to Cloud Trace, metrics to Cloud Monitoring and logs to Cloud Logging",
+  endpoints: (c) => {
+    const overrides = [c.trace?.endpoint, c.metric?.endpoint, c.log?.endpoint].filter(
+      (e): e is string => typeof e === "string" && e !== "",
+    );
+    return [`googlecloud://projects/${c.project ?? "(detected)"}`, ...overrides];
+  },
+});

package/src/components/extensions.ts

@@ -0,0 +1,51 @@
+/**
+ * Built-in extensions: health_check, pprof, zpages.
+ */
+
+import { defineBuiltin } from "../define";
+import type { TLSServerSettings } from "./common";
+
+export interface HealthCheckExtensionConfig {
+  /** Default `localhost:13133`. */
+  endpoint?: string;
+  path?: string;
+  tls?: TLSServerSettings;
+  response_body?: { healthy?: string; unhealthy?: string };
+}
+
+/** Serves an HTTP health endpoint for liveness and readiness probes. */
+export const HealthCheckExtension = defineBuiltin<HealthCheckExtensionConfig, "extension", "health_check">({
+  kind: "extension",
+  type: "health_check",
+  description: "Serves an HTTP health endpoint for liveness and readiness probes",
+  endpoints: (c) => [`${c.endpoint ?? "localhost:13133"}${c.path ?? "/"}`],
+});
+
+export interface PprofExtensionConfig {
+  /** Default `localhost:1777`. */
+  endpoint?: string;
+  block_profile_fraction?: number;
+  mutex_profile_fraction?: number;
+  save_to_file?: string;
+}
+
+/** Serves Go's net/http/pprof profiling endpoints. */
+export const PprofExtension = defineBuiltin<PprofExtensionConfig, "extension", "pprof">({
+  kind: "extension",
+  type: "pprof",
+  description: "Serves Go pprof profiling endpoints",
+  endpoints: (c) => [c.endpoint ?? "localhost:1777"],
+});
+
+export interface ZPagesExtensionConfig {
+  /** Default `localhost:55679`. */
+  endpoint?: string;
+}
+
+/** Serves in-process zPages for live debugging of pipelines. */
+export const ZPagesExtension = defineBuiltin<ZPagesExtensionConfig, "extension", "zpages">({
+  kind: "extension",
+  type: "zpages",
+  description: "Serves zPages for live debugging of receivers and exporters",
+  endpoints: (c) => [c.endpoint ?? "localhost:55679"],
+});

package/src/components/index.ts

@@ -0,0 +1,5 @@
+export * from "./common";
+export * from "./receivers";
+export * from "./processors";
+export * from "./exporters";
+export * from "./extensions";

package/src/components/processors.ts

@@ -0,0 +1,208 @@
+/**
+ * Built-in processors: batch, memory_limiter, resource, attributes,
+ * k8sattributes, resourcedetection.
+ */
+
+import { defineBuiltin } from "../define";
+import type { AttributeAction, Duration } from "./common";
+
+// ── batch ────────────────────────────────────────────────────────────
+
+export interface BatchProcessorConfig {
+  timeout?: Duration;
+  send_batch_size?: number;
+  send_batch_max_size?: number;
+  metadata_keys?: string[];
+  metadata_cardinality_limit?: number;
+}
+
+/** Batches telemetry before export, to cut request count and compress better. */
+export const BatchProcessor = defineBuiltin<BatchProcessorConfig, "processor", "batch">({
+  kind: "processor",
+  type: "batch",
+  description: "Groups telemetry into batches before export",
+  validate: (c) =>
+    c.send_batch_max_size !== undefined && c.send_batch_max_size !== 0 && c.send_batch_size !== undefined && c.send_batch_max_size < c.send_batch_size
+      ? [`send_batch_max_size (${c.send_batch_max_size}) is below send_batch_size (${c.send_batch_size}); the collector rejects this`]
+      : [],
+});
+
+// ── memory_limiter ───────────────────────────────────────────────────
+
+export interface MemoryLimiterProcessorConfig {
+  check_interval: Duration;
+  limit_mib?: number;
+  spike_limit_mib?: number;
+  limit_percentage?: number;
+  spike_limit_percentage?: number;
+}
+
+/** Refuses data when the collector nears its memory limit. Belongs first in every pipeline. */
+export const MemoryLimiterProcessor = defineBuiltin<MemoryLimiterProcessorConfig, "processor", "memory_limiter">({
+  kind: "processor",
+  type: "memory_limiter",
+  description: "Refuses data when the collector nears a memory limit; runs first in a pipeline",
+  validate: (c) => {
+    const problems: string[] = [];
+    if (c.limit_mib === undefined && c.limit_percentage === undefined) {
+      problems.push("set limit_mib or limit_percentage; with neither the collector refuses to start");
+    }
+    if (c.limit_mib !== undefined && c.spike_limit_mib !== undefined && c.spike_limit_mib >= c.limit_mib) {
+      problems.push(`spike_limit_mib (${c.spike_limit_mib}) must be below limit_mib (${c.limit_mib})`);
+    }
+    if (c.limit_percentage !== undefined && (c.limit_percentage <= 0 || c.limit_percentage > 100)) {
+      problems.push(`limit_percentage (${c.limit_percentage}) must be between 1 and 100`);
+    }
+    return problems;
+  },
+});
+
+// ── resource ─────────────────────────────────────────────────────────
+
+export interface ResourceProcessorConfig {
+  attributes: AttributeAction[];
+}
+
+/** Inserts, updates or deletes resource attributes. */
+export const ResourceProcessor = defineBuiltin<ResourceProcessorConfig, "processor", "resource">({
+  kind: "processor",
+  type: "resource",
+  description: "Inserts, updates or deletes resource attributes",
+  validate: (c) => actionProblems(c.attributes, "attributes"),
+});
+
+// ── attributes ───────────────────────────────────────────────────────
+
+export interface AttributesMatch {
+  match_type: "strict" | "regexp";
+  services?: string[];
+  span_names?: string[];
+  log_bodies?: string[];
+  log_severity_texts?: string[];
+  metric_names?: string[];
+  attributes?: Array<{ key: string; value?: unknown }>;
+  resources?: Array<{ key: string; value?: unknown }>;
+  libraries?: Array<{ name: string; version?: string }>;
+}
+
+export interface AttributesProcessorConfig {
+  actions: AttributeAction[];
+  include?: AttributesMatch;
+  exclude?: AttributesMatch;
+}
+
+/** Inserts, updates, hashes or deletes span, log and metric attributes. */
+export const AttributesProcessor = defineBuiltin<AttributesProcessorConfig, "processor", "attributes">({
+  kind: "processor",
+  type: "attributes",
+  description: "Inserts, updates, hashes or deletes span, log and metric attributes",
+  validate: (c) => actionProblems(c.actions, "actions"),
+});
+
+function actionProblems(actions: AttributeAction[] | undefined, field: string): string[] {
+  if (!actions || actions.length === 0) return [`${field} is empty, so the processor changes nothing`];
+  const problems: string[] = [];
+  actions.forEach((a, i) => {
+    if (a.action !== "extract" && !a.key) problems.push(`${field}[${i}] (${a.action}) needs a key`);
+    if (a.action === "extract" && !a.pattern) problems.push(`${field}[${i}] (extract) needs a pattern`);
+    if (
+      (a.action === "insert" || a.action === "update" || a.action === "upsert") &&
+      a.value === undefined &&
+      a.from_attribute === undefined &&
+      a.from_context === undefined
+    ) {
+      problems.push(`${field}[${i}] (${a.action}) needs value, from_attribute or from_context`);
+    }
+    if (a.action === "convert" && !a.converted_type) problems.push(`${field}[${i}] (convert) needs converted_type`);
+  });
+  return problems;
+}
+
+// ── k8sattributes ────────────────────────────────────────────────────
+
+export interface K8sFieldExtract {
+  tag_name?: string;
+  key?: string;
+  key_regex?: string;
+  from: "pod" | "namespace" | "node";
+}
+
+export interface K8sPodAssociationSource {
+  from: "resource_attribute" | "connection";
+  name?: string;
+}
+
+export interface K8sAttributesProcessorConfig {
+  auth_type?: "none" | "serviceAccount" | "kubeConfig" | "tls";
+  passthrough?: boolean;
+  filter?: {
+    node?: string;
+    node_from_env_var?: string;
+    namespace?: string;
+    fields?: Array<{ key: string; value: string; op?: "equals" | "not-equals" }>;
+    labels?: Array<{ key: string; value: string; op?: "equals" | "not-equals" | "exists" | "does-not-exist" }>;
+  };
+  extract?: {
+    metadata?: string[];
+    labels?: K8sFieldExtract[];
+    annotations?: K8sFieldExtract[];
+    otel_annotations?: boolean;
+  };
+  pod_association?: Array<{ sources: K8sPodAssociationSource[] }>;
+  exclude?: { pods?: Array<{ name: string }> };
+  wait_for_metadata?: boolean;
+  wait_for_metadata_timeout?: Duration;
+}
+
+/** Adds Kubernetes pod, namespace and node metadata to telemetry. */
+export const K8sAttributesProcessor = defineBuiltin<K8sAttributesProcessorConfig, "processor", "k8sattributes">({
+  kind: "processor",
+  type: "k8sattributes",
+  description: "Adds Kubernetes pod, namespace and node metadata to telemetry",
+});
+
+// ── resourcedetection ────────────────────────────────────────────────
+
+export type ResourceDetector =
+  | "env"
+  | "system"
+  | "docker"
+  | "gcp"
+  | "ec2"
+  | "ecs"
+  | "eks"
+  | "elasticbeanstalk"
+  | "lambda"
+  | "azure"
+  | "aks"
+  | "consul"
+  | "heroku"
+  | "openshift"
+  | "k8snode"
+  | "kubeadm"
+  | "dynatrace";
+
+export interface ResourceDetectionProcessorConfig {
+  detectors: Array<ResourceDetector | (string & {})>;
+  timeout?: Duration;
+  override?: boolean;
+  /** Per-detector settings, e.g. `system: { hostname_sources: ["os"] }`. */
+  system?: Record<string, unknown>;
+  ec2?: Record<string, unknown>;
+  gcp?: Record<string, unknown>;
+  azure?: Record<string, unknown>;
+  k8snode?: Record<string, unknown>;
+  docker?: Record<string, unknown>;
+}
+
+/** Detects the host's resource attributes (cloud, container, host) and adds them. */
+export const ResourceDetectionProcessor = defineBuiltin<
+  ResourceDetectionProcessorConfig,
+  "processor",
+  "resourcedetection"
+>({
+  kind: "processor",
+  type: "resourcedetection",
+  description: "Detects cloud, container and host resource attributes",
+  validate: (c) => (c.detectors?.length ? [] : ["detectors is empty, so nothing is detected"]),
+});