otel.c File Reference

Go to the source code of this file.

Macros
#define	ASCIICHAT_OTEL_IMPLEMENTATION
#define	OTEL_NAME_BUFFER_SIZE   256
#define	OTEL_VERSION_BUFFER_SIZE   32
#define	OTEL_BODY_BUFFER_SIZE   4096
#define	OTEL_URL_BUFFER_SIZE   2048
#define	OTEL_NAME_EXTENDED_BUFFER_SIZE   1200
#define	OTEL_WAIT_SNAPSHOT_CAPACITY   256
#define	ASCII_OTEL_OPERATION(id, name, realtime)
#define	ASCII_OTEL_METRIC(id, name, type, unit)
#define	ASCII_STATS_COUNTER(id, metric_id, name, unit)
#define	ASCII_STATS_GAUGE(id, metric_id, name, unit)
#define	ASCII_STATS_DURATION(id, metric_id, name, unit)
#define	ASCII_STATS_COUNTER(id, metric_id, name, unit)
#define	ASCII_STATS_GAUGE(id, metric_id, name, unit)
#define	ASCII_STATS_DURATION(id, metric_id, name, unit)

Enumerations
enum	{ stats_metric_count }

Functions
const char *	ascii_otel_current_operation (void)
bool	ascii_otel_enabled (void)
void	ascii_otel_metric (ascii_otel_metric_t metric, double value)
ascii_otel_metric_t	ascii_otel_stats_metric (stats_record_kind_t kind, unsigned id)
void	ascii_otel_stats_attach (stats_scope_t *scope)
void	ascii_otel_pipeline_progress (unsigned stage, unsigned expected)
double	ascii_otel_pipeline_age (uint64_t now, uint64_t capture, uint64_t progress, bool expected)
void	ascii_otel_scope_begin (ascii_otel_scope_t *s, ascii_otel_operation_t op)
void	ascii_otel_scope_parent (ascii_otel_scope_t *s, ascii_otel_operation_t op, const gotel_context_t *parent)
void	ascii_otel_scope_end (ascii_otel_scope_t *s)
void	ascii_otel_ui_usage (const char *screen, const char *event, uint64_t duration_ns)
void	ascii_otel_call_session_used (const char *session_string)
void	ascii_otel_packet (ascii_otel_scope_t *scope, uint16_t type, size_t payload_size, const char *action, int transport)
void	ascii_otel_shutdown (void)
asciichat_error_t	ascii_otel_init (const char *mode, int argc, char **argv)
void	ascii_otel_log (int level, const char *file, int line, const char *function, const char *format, va_list args)
gotel_context_t	ascii_otel_context (void)
void	ascii_otel_scope_int (ascii_otel_scope_t *s, const char *key, int64_t value)
void	ascii_otel_scope_string (ascii_otel_scope_t *s, const char *key, const char *value)
void	ascii_otel_exit (int code)
void	ascii_otel_frame_rejected (const char *validator, const char *reason, size_t bytes, uint32_t width, uint32_t height, asciichat_error_t code)
ascii_otel_operation_t	ascii_otel_failure_operation (asciichat_error_t code, const char *origin)
void	ascii_otel_error_code (asciichat_error_t code, const char *message)
void	ascii_otel_error (const char *message)
void	ascii_otel_http (ascii_otel_scope_t *s, const char *hostname, const char *path)
void	ascii_otel_http_status (ascii_otel_scope_t *s, int status)
int	ascii_otel_sqlite_prepare (sqlite3 *db, const char *sql, sqlite3_stmt **statement)
void	ascii_otel_sqlite (sqlite3 *db, const gotel_query_t *queries, size_t count)
void	ascii_otel_sqlite_catalog (sqlite3 *db, const gotel_query_catalog_t *catalog)

Detailed Description

Native telemetry lifecycle and ascii-chat instrumentation.

Definition in file otel.c.

Macro Definition Documentation

ASCII_OTEL_METRIC

#define ASCII_OTEL_METRIC	(		id,
			name,
			type,
			unit )

Value:

  {name, unit, OTLP_METRIC_##type, metric_bounds, sizeof(metric_bounds) / sizeof(metric_bounds[0])},

ASCII_OTEL_OPERATION

#define ASCII_OTEL_OPERATION	(		id,
			name,
			realtime )

Value:

{name, realtime},

ASCII_STATS_COUNTER [1/2]

#define ASCII_STATS_COUNTER	(		id,
			metric_id,
			name,
			unit )

Value:

  case (STATS_RECORD_COUNTER << 16) | STATS_COUNTER_##id:                                                              \
    metric = ASCII_OTEL_METRIC_##metric_id;                                                                            \
    break;

ASCII_STATS_COUNTER [2/2]

#define ASCII_STATS_COUNTER	(		id,
			metric_id,
			name,
			unit )

Value:

+1

ASCII_STATS_DURATION [1/2]

#define ASCII_STATS_DURATION	(		id,
			metric_id,
			name,
			unit )

Value:

  case (STATS_RECORD_DURATION << 16) | STATS_DURATION_##id:                                                            \
    metric = ASCII_OTEL_METRIC_##metric_id;                                                                            \
    break;

ASCII_STATS_DURATION [2/2]

#define ASCII_STATS_DURATION	(		id,
			metric_id,
			name,
			unit )

Value:

+1

ASCII_STATS_GAUGE [1/2]

#define ASCII_STATS_GAUGE	(		id,
			metric_id,
			name,
			unit )

Value:

  case (STATS_RECORD_GAUGE << 16) | STATS_GAUGE_##id:                                                                  \
    metric = ASCII_OTEL_METRIC_##metric_id;                                                                            \
    break;

ASCII_STATS_GAUGE [2/2]

#define ASCII_STATS_GAUGE	(		id,
			metric_id,
			name,
			unit )

Value:

+1

ASCIICHAT_OTEL_IMPLEMENTATION

#define ASCIICHAT_OTEL_IMPLEMENTATION

Definition at line 2 of file otel.c.

OTEL_BODY_BUFFER_SIZE

#define OTEL_BODY_BUFFER_SIZE   4096

Definition at line 7 of file otel.c.

Referenced by ascii_otel_error(), ascii_otel_error_code(), and ascii_otel_log().

OTEL_NAME_BUFFER_SIZE

#define OTEL_NAME_BUFFER_SIZE   256

Definition at line 5 of file otel.c.

Referenced by ascii_otel_packet().

OTEL_NAME_EXTENDED_BUFFER_SIZE

#define OTEL_NAME_EXTENDED_BUFFER_SIZE   1200

Definition at line 9 of file otel.c.

Referenced by ascii_otel_http().

OTEL_URL_BUFFER_SIZE

#define OTEL_URL_BUFFER_SIZE   2048

Definition at line 8 of file otel.c.

Referenced by ascii_otel_http().

OTEL_VERSION_BUFFER_SIZE

#define OTEL_VERSION_BUFFER_SIZE   32

Definition at line 6 of file otel.c.

Referenced by ascii_otel_packet().

OTEL_WAIT_SNAPSHOT_CAPACITY

#define OTEL_WAIT_SNAPSHOT_CAPACITY   256

Definition at line 12 of file otel.c.

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
stats_metric_count

Definition at line 168 of file otel.c.

     {
  stats_metric_count = 0
#define ASCII_STATS_COUNTER(id, metric_id, name, unit) +1
#define ASCII_STATS_GAUGE(id, metric_id, name, unit) +1
#define ASCII_STATS_DURATION(id, metric_id, name, unit) +1
#include <ascii-chat/stats/telemetry.def>
#undef ASCII_STATS_COUNTER
#undef ASCII_STATS_GAUGE
#undef ASCII_STATS_DURATION
};

Function Documentation

ascii_otel_call_session_used()

void ascii_otel_call_session_used

(

const char *

session_string

)

Definition at line 443 of file otel.c.

                                                              {
  if (!session_string || !session_string[0])
    return;
  // Call usage must not inherit a realtime packet's sampling decision.
  gotel_context_t root = {0};
  ASCII_OTEL_SCOPE_PARENT(CALL_SESSION_USED, &root);
  ASCII_OTEL_ATTR_STRING("ascii-chat.session.string", session_string);
}

References ASCII_OTEL_ATTR_STRING, and ASCII_OTEL_SCOPE_PARENT.

ascii_otel_context()

gotel_context_t ascii_otel_context

(

void

)

Definition at line 725 of file otel.c.

                                         {
  return gotel_current_context();
}

Referenced by ascii_otel_error_code(), ascii_otel_frame_rejected(), and mcp_dispatch().

ascii_otel_current_operation()

const char * ascii_otel_current_operation

(

void

)

Definition at line 153 of file otel.c.

                                               {
  return current_scope && current_scope->scope.operation < ASCII_OTEL_OPERATION_COUNT
             ? operations[current_scope->scope.operation].name
             : "";
}

References ASCII_OTEL_OPERATION_COUNT.

Referenced by ascii_otel_error_code().

ascii_otel_enabled()

bool ascii_otel_enabled

(

void

)

Definition at line 158 of file otel.c.

                              {
  return atomic_ptr_load(&host) != NULL;
}

Referenced by ascii_otel_error_code(), and ascii_otel_pipeline_progress().

ascii_otel_error()

void ascii_otel_error

(

const char *

message

)

Definition at line 804 of file otel.c.

                                           {
  char redacted[OTEL_BODY_BUFFER_SIZE];
  int written = safe_snprintf(redacted, sizeof(redacted), "%s", message ? message : "");
  if (written < 0)
    return;
  url_redact_diagnostic(redacted, (size_t)written >= sizeof(redacted));
  gotel_current_error("ascii_chat.error", redacted);
}

References OTEL_BODY_BUFFER_SIZE, safe_snprintf(), and url_redact_diagnostic().

Referenced by mcp_error().

ascii_otel_error_code()

void ascii_otel_error_code	(	asciichat_error_t	code,
		const char *	message )

Definition at line 776 of file otel.c.

                                                                        {
  if (code == ASCIICHAT_OK || code == ERROR_SIGNAL_INTERRUPT || code == ERROR_NETWORK_INCOMPLETE)
    return;
  char redacted[OTEL_BODY_BUFFER_SIZE];
  int written = safe_snprintf(redacted, sizeof(redacted), "%s", message ? message : "");
  if (written < 0)
    return;
  url_redact_diagnostic(redacted, (size_t)written >= sizeof(redacted));
  gotel_current_error("ascii_chat.error", redacted);
  if (!ascii_otel_enabled())
    return;
  const char *origin = ascii_otel_current_operation();
  ascii_otel_operation_t operation = ascii_otel_failure_operation(code, origin);
  if (operation == ASCII_OTEL_OPERATION_COUNT)
    return;
  const char *category = operation == ASCII_OTEL_FAILURE_CRYPTO     ? "crypto"
                         : operation == ASCII_OTEL_FAILURE_PROTOCOL ? "protocol"
                                                                    : "discovery";
  gotel_context_t parent = ascii_otel_context();
  ascii_otel_scope_t report __attribute__((cleanup(ascii_otel_scope_end))) = {0};
  if (!scope_retained(&report, operation, &parent))
    return;
  gotel_attr_string(&report.scope, "ascii_chat.failure.category", category);
  gotel_attr_string(&report.scope, "ascii_chat.failure.operation", origin);
  gotel_attr_int(&report.scope, "asciichat_errno.code", code);
  gotel_attr_string(&report.scope, "asciichat_errno.code_message", asciichat_error_string(code));
  gotel_error(&report.scope, category, redacted);
}

References ascii_otel_context(), ascii_otel_current_operation(), ascii_otel_enabled(), ascii_otel_failure_operation(), ASCII_OTEL_OPERATION_COUNT, ascii_otel_scope_end(), ASCIICHAT_OK, ERROR_NETWORK_INCOMPLETE, ERROR_SIGNAL_INTERRUPT, OTEL_BODY_BUFFER_SIZE, safe_snprintf(), and url_redact_diagnostic().

ascii_otel_exit()

void ascii_otel_exit

(

int

code

)

Definition at line 736 of file otel.c.

                               {
  gotel_attr_int(&command_scope, "process.exit.code", code);
  if (code)
    gotel_error(&command_scope, "ascii_chat.exit", "Command failed");
  else {
    command_scope.failed = false;
    if (command_scope.span)
      (void)otel_status(otlp_span_set_status(command_scope.span, OTLP_STATUS_CODE_UNSET, ""), "otlp_span_set_status");
  }
}

Referenced by main().

ascii_otel_failure_operation()

ascii_otel_operation_t ascii_otel_failure_operation	(	asciichat_error_t	code,
		const char *	origin )

Definition at line 763 of file otel.c.

                                                                                                {
  if (code == ASCIICHAT_OK || code == ERROR_SIGNAL_INTERRUPT || code == ERROR_NETWORK_INCOMPLETE)
    return ASCII_OTEL_OPERATION_COUNT;
  if ((code >= ERROR_CRYPTO && code <= ERROR_CRYPTO_VERIFICATION) || code == ERROR_CRYPTO_INIT ||
      code == ERROR_INVALID_PASSWORD || code == ERROR_INVALID_SIGNATURE)
    return ASCII_OTEL_FAILURE_CRYPTO;
  if (code == ERROR_NETWORK_PROTOCOL || code == ERROR_NETWORK_SIZE || code == ERROR_UNKNOWN_PACKET)
    return ASCII_OTEL_FAILURE_PROTOCOL;
  if ((code >= ERROR_SESSION_NOT_FOUND && code <= ERROR_SESSION_FULL) || code == ERROR_ACDS_STRING_TAKEN ||
      code == ERROR_ACDS_STRING_INVALID || (origin && !strncmp(origin, "ascii-chat.discovery.", 21)))
    return ASCII_OTEL_FAILURE_DISCOVERY;
  return ASCII_OTEL_OPERATION_COUNT;
}

References ASCII_OTEL_OPERATION_COUNT, ASCIICHAT_OK, ERROR_ACDS_STRING_INVALID, ERROR_ACDS_STRING_TAKEN, ERROR_CRYPTO, ERROR_CRYPTO_INIT, ERROR_CRYPTO_VERIFICATION, ERROR_INVALID_PASSWORD, ERROR_INVALID_SIGNATURE, ERROR_NETWORK_INCOMPLETE, ERROR_NETWORK_PROTOCOL, ERROR_NETWORK_SIZE, ERROR_SESSION_FULL, ERROR_SESSION_NOT_FOUND, ERROR_SIGNAL_INTERRUPT, and ERROR_UNKNOWN_PACKET.

Referenced by ascii_otel_error_code().

ascii_otel_frame_rejected()

void ascii_otel_frame_rejected	(	const char *	validator,
		const char *	reason,
		size_t	bytes,
		uint32_t	width,
		uint32_t	height,
		asciichat_error_t	code )

Definition at line 746 of file otel.c.

                                                       {
  ascii_otel_metric(ASCII_OTEL_METRIC_FRAME_VALIDATION_REJECTED, 1);
  gotel_context_t parent = ascii_otel_context();
  ascii_otel_scope_t otel_scope __attribute__((cleanup(ascii_otel_scope_end))) = {0};
  if (!scope_retained(&otel_scope, ASCII_OTEL_FRAME_VALIDATION_REJECTED, &parent))
    return;
  ASCII_OTEL_ATTR_STRING("frame.validation.validator", validator);
  ASCII_OTEL_ATTR_STRING("frame.validation.reason", reason);
  ASCII_OTEL_ATTR_INT("frame.size_bytes", (int64_t)bytes);
  ASCII_OTEL_ATTR_INT("frame.width", width);
  ASCII_OTEL_ATTR_INT("frame.height", height);
  ASCII_OTEL_ATTR_INT("asciichat_errno.code", code);
  ASCII_OTEL_ATTR_STRING("asciichat_errno.code_message", asciichat_error_string(code));
  if (otel_scope.retained)
    gotel_error(&otel_scope.scope, "ascii_chat.invalid_frame", reason);
}

References ASCII_OTEL_ATTR_INT, ASCII_OTEL_ATTR_STRING, ascii_otel_context(), ascii_otel_metric(), ascii_otel_scope_end(), height, and width.

Referenced by session_frame_validate_contract().

ascii_otel_http()

void ascii_otel_http	(	ascii_otel_scope_t *	s,
		const char *	hostname,
		const char *	path )

Definition at line 812 of file otel.c.

                                                                                    {
  if (!s->retained || !hostname || !path)
    return;
  gotel_error(&s->scope, "http.transport", "HTTP operation did not complete");
  char url[OTEL_URL_BUFFER_SIZE], name[OTEL_NAME_EXTENDED_BUFFER_SIZE];
  int n = safe_snprintf(url, sizeof(url), "https://%s%s", hostname, path);
  if (n >= 0 && (size_t)n < sizeof(url) &&
      otel_status(gotel_http_name(name, sizeof(name), "ascii-chat", false, "GET", url), "Name HTTP telemetry span") ==
          ASCIICHAT_OK) {
    if (s->scope.span)
      (void)otel_status(otlp_span_set_name(s->scope.span, name), "otlp_span_set_name");
    gotel_http_attributes(&s->scope, "GET", 0);
    gotel_attr_string(&s->scope, "server.address", hostname);
    gotel_attr_string(&s->scope, "url.scheme", "https");
  }
}

References ASCIICHAT_OK, OTEL_NAME_EXTENDED_BUFFER_SIZE, OTEL_URL_BUFFER_SIZE, ascii_otel_scope::retained, safe_snprintf(), and ascii_otel_scope::scope.

Referenced by https_get().

ascii_otel_http_status()

void ascii_otel_http_status	(	ascii_otel_scope_t *	s,
		int	status )

Definition at line 828 of file otel.c.

                                                               {
  if (s->retained) {
    if (status > 0 && status < 400) {
      s->scope.failed = false;
      if (s->scope.span) {
        (void)otel_status(otlp_span_set_status(s->scope.span, OTLP_STATUS_CODE_UNSET, ""), "otlp_span_set_status");
        gotel_attr_string(&s->scope, "error.type", "");
      }
    }
    gotel_http_attributes(&s->scope, "GET", status);
  }
}

References ascii_otel_scope::retained, and ascii_otel_scope::scope.

Referenced by https_get().

ascii_otel_init()

asciichat_error_t ascii_otel_init	(	const char *	mode,
		int	argc,
		char **	argv )

Definition at line 555 of file otel.c.

                                                                           {
  // Test mode is a hard export prohibition, including explicit endpoints and CLI overrides.
  if (is_test_environment())
    return ASCIICHAT_OK;
  const options_t *o = options_get();
  const char *endpoint = o->otel_endpoint;
  if (!endpoint || endpoint[0] == '\0')
    return ASCIICHAT_OK;
  bool endpoint_cli = false, timeout_cli = false;
  for (int i = 1; i < argc; ++i) {
    endpoint_cli |= !strcmp(argv[i], "--otel-endpoint") || !strncmp(argv[i], "--otel-endpoint=", 16);
    timeout_cli |= !strcmp(argv[i], "--otel-timeout") || !strncmp(argv[i], "--otel-timeout=", 15);
  }
  unsigned signals;
  asciichat_error_t parsed = otel_status(gotel_parse_signals(o->otel_enabled_telemetry, &signals),
                                         "Parse otel-enabled-telemetry (traces,logs,metrics or none)");
  if (parsed != ASCIICHAT_OK)
    return parsed;
  if (!isfinite(o->otel_realtime_sample_rate) || o->otel_realtime_sample_rate < 0 || o->otel_realtime_sample_rate > 1 ||
      o->otel_queue_capacity < 2 || (o->otel_queue_capacity & (o->otel_queue_capacity - 1)) || o->otel_timeout < 1 ||
      o->otel_metrics_interval < 1 || o->otel_realtime_max_per_second < 1)
    return SET_ERRNO(ERROR_CONFIG, "Invalid telemetry sampling, queue capacity, or interval");
  const char *log_names[] = {"dev", "debug", "info", "warn", "error", "fatal"};
  const int log_levels[] = {LOG_DEV, LOG_DEBUG, LOG_INFO, LOG_WARN, LOG_ERROR, LOG_FATAL};
  minimum_log_level = -1;
  for (size_t i = 0; i < sizeof(log_levels) / sizeof(log_levels[0]); ++i)
    if (strcmp(o->otel_log_level, log_names[i]) == 0)
      minimum_log_level = log_levels[i];
  if (minimum_log_level < 0)
    return SET_ERRNO(ERROR_CONFIG, "Invalid otel-log-level");
  if (!signals)
    return ASCIICHAT_OK;
  gotel_options_t config = {0};
  config.application_name = "ascii-chat";
  config.disable_span_name_prefix = true;
  char service_name[OPTIONS_BUFF_SIZE];
  int n = safe_snprintf(service_name, sizeof(service_name), "ascii-chat-%s", mode);
  if (n < 0 || (size_t)n >= sizeof(service_name))
    return SET_ERRNO(ERROR_CONFIG, "Telemetry service name too long");
  config.exporter.service_name = service_name;
  // The exporter observes its batch interval during final flush as well.
  // Keep it short enough to deliver all signals within the shutdown budget.
  config.exporter.batch_ms = 25;
  config.exporter.queue_capacity = (size_t)o->otel_queue_capacity;
  config.exporter.connect_timeout_ms = (uint32_t)o->otel_timeout;
  config.exporter.read_timeout_ms = (uint32_t)o->otel_timeout;
  config.exporter.flush_timeout_ms = (uint32_t)o->otel_timeout;
  otlp_resource_attr_t resources[] = {
      {.key = "ascii_chat.mode", .value = {.type = OTLP_VALUE_STRING, .v = {.string_val = mode}}},
      {.key = "service.version", .value = {.type = OTLP_VALUE_STRING, .v = {.string_val = ASCII_CHAT_VERSION_FULL}}},
  };
  config.exporter.resource_attributes = resources;
  config.exporter.n_resource_attributes = sizeof(resources) / sizeof(resources[0]);
  config.signals = signals;
  config.realtime_sample_rate = o->otel_realtime_sample_rate;
  config.realtime_max_per_second = (uint32_t)o->otel_realtime_max_per_second;
  config.metrics_interval_ms = (uint32_t)o->otel_metrics_interval;
  config.monotonic_ns = time_get_ns;
  config.realtime_ns = telemetry_realtime_ns;
  config.operations = operations;
  config.operation_count = ASCII_OTEL_OPERATION_COUNT;
  config.exporter_event = exporter_event;
  config.metrics = metrics;
  config.metric_count = ASCII_OTEL_METRIC_COUNT;
#ifndef NDEBUG
  config.watchdog.snapshot = watchdog_snapshot;
  config.watchdog.decorate = watchdog_decorate;
  config.watchdog.operation = ASCII_OTEL_THREAD_DEADLOCK;
  config.watchdog.metric = ASCII_OTEL_METRIC_DEADLOCK_THREADS;
#endif
  gotel_command_args_t command_args = {0};
  // Addresses are positional in native client/server modes, with optional ports.
  char address_port[OPTIONS_BUFF_SIZE + 32], address6_port[OPTIONS_BUFF_SIZE + 32];
  char address_brackets[OPTIONS_BUFF_SIZE + 32], address6_brackets[OPTIONS_BUFF_SIZE + 32];
  char address_brackets_port[OPTIONS_BUFF_SIZE + 32], address6_brackets_port[OPTIONS_BUFF_SIZE + 32];
  SAFE_SNPRINTF(address_port, sizeof(address_port), "%s:%d", o->address, o->port);
  SAFE_SNPRINTF(address6_port, sizeof(address6_port), "%s:%d", o->address6, o->port);
  SAFE_SNPRINTF(address_brackets, sizeof(address_brackets), "[%s]", o->address);
  SAFE_SNPRINTF(address6_brackets, sizeof(address6_brackets), "[%s]", o->address6);
  SAFE_SNPRINTF(address_brackets_port, sizeof(address_brackets_port), "[%s]:%d", o->address, o->port);
  SAFE_SNPRINTF(address6_brackets_port, sizeof(address6_brackets_port), "[%s]:%d", o->address6, o->port);
  const char *sensitive_values[] = {o->address,       o->address6,       address_port,          address6_port,
                                    address_brackets, address6_brackets, address_brackets_port, address6_brackets_port};
  gotel_command_policy_t argument_policy = {
#ifdef NDEBUG
      .mode = GOTEL_COMMAND_REDACT_SELECTED,
#else
      .mode = GOTEL_COMMAND_REDACT_NONE,
#endif
      .rules = command_argument_rules,
      .sensitive_values = sensitive_values,
      .sensitive_value_count = sizeof(sensitive_values) / sizeof(sensitive_values[0]),
      .rule_count = sizeof(command_argument_rules) / sizeof(command_argument_rules[0]),
  };
  asciichat_error_t arguments_status =
      otel_status(gotel_command_args_init_policy(&command_args, "ascii-chat", mode, argc, (const char *const *)argv,
                                                 &argument_policy),
                  "Sanitize telemetry command arguments");
  if (arguments_status != ASCIICHAT_OK)
    return arguments_status;
  config.argc = command_args.argc;
  config.argv = command_args.argv;
  gotel_env_storage_t env;
  asciichat_error_t env_status =
      otel_status(gotel_options_apply_env(&config, &env, OPT_OTEL_ENDPOINT_DEFAULT), "Configure OTEL environment");
  if (env_status == ASCIICHAT_OK &&
      (endpoint_cli || SAFE_GETENV("ASCII_CHAT_OTEL_ENDPOINT") || strcmp(endpoint, OPT_OTEL_ENDPOINT_DEFAULT)))
    env_status = otel_status(gotel_options_set_endpoint(&config, &env, endpoint), "Configure telemetry endpoint");
  if (timeout_cli || SAFE_GETENV("ASCII_CHAT_OTEL_TIMEOUT")) {
    config.exporter.connect_timeout_ms = (uint32_t)o->otel_timeout;
    config.exporter.read_timeout_ms = (uint32_t)o->otel_timeout;
    config.exporter.flush_timeout_ms = (uint32_t)o->otel_timeout;
  }
  if (*o->otel_ca_file)
    config.tls_ca_file = o->otel_ca_file;
  if (env_status != ASCIICHAT_OK || !config.signals || !config.exporter.endpoint) {
    gotel_command_args_destroy(&command_args);
    return env_status;
  }
  gotel_host_t *h = NULL;
  asciichat_error_t created = otel_status(gotel_create(&config, &h), "Initialize telemetry exporter");
  if (created != ASCIICHAT_OK) {
    gotel_command_args_destroy(&command_args);
    return created;
  }
  gotel_set_logger(h, exporter_diagnostic, NULL);
  shutdown_timeout_ns = (uint64_t)o->otel_timeout * NS_PER_MS_INT;
  atomic_store(&stopping, false);
  atomic_store(&exporter_queue_capacity, config.exporter.queue_capacity);
  atomic_store(&worker_done, false);
  if (platform_thread_create(&worker, "otel_export", export_worker, h) != 0) {
    gotel_destroy(h);
    gotel_command_args_destroy(&command_args);
    return SET_ERRNO(ERROR_THREAD, "Cannot start telemetry exporter");
  }
  worker_started = true;
  (void)atexit(ascii_otel_shutdown);
  atomic_ptr_store(&host, h);
  gotel_begin(h, &command_scope, ASCII_OTEL_CLI, NULL);
  (void)otel_status(gotel_command_args_set_span(&command_scope, &command_args), "Attach telemetry command arguments");
  gotel_command_args_destroy(&command_args);
 
  log_info("Telemetry enabled: %s (%s)", config.exporter.endpoint, o->otel_enabled_telemetry);
  return ASCIICHAT_OK;
}

References options_state::address, options_state::address6, ASCII_OTEL_METRIC_COUNT, ASCII_OTEL_OPERATION_COUNT, ascii_otel_shutdown(), ASCIICHAT_OK, ERROR_CONFIG, ERROR_THREAD, LOG_DEBUG, LOG_DEV, LOG_ERROR, LOG_FATAL, LOG_INFO, log_info, LOG_WARN, NS_PER_MS_INT, OPT_OTEL_ENDPOINT_DEFAULT, OPTIONS_BUFF_SIZE, options_get(), options_state::otel_ca_file, options_state::otel_enabled_telemetry, options_state::otel_endpoint, options_state::otel_log_level, options_state::otel_metrics_interval, options_state::otel_queue_capacity, options_state::otel_realtime_max_per_second, options_state::otel_realtime_sample_rate, options_state::otel_timeout, options_state::port, SAFE_GETENV, SAFE_SNPRINTF, safe_snprintf(), and SET_ERRNO.

Referenced by main().

ascii_otel_log()

void ascii_otel_log	(	int	level,
		const char *	file,
		int	line,
		const char *	function,
		const char *	format,
		va_list	args )

Definition at line 700 of file otel.c.

                                                                                                                   {
  (void)file;
  (void)line;
  (void)function;
  if (in_log || level < minimum_log_level || !atomic_ptr_load(&host))
    return;
  in_log = true;
  gotel_host_t *h = retain();
  if (h) {
    char body[OTEL_BODY_BUFFER_SIZE];
    int n = safe_vsnprintf(body, sizeof(body), format, args);
    if (n >= 0) {
      url_redact_diagnostic(body, (size_t)n >= sizeof(body));
      otlp_severity_t severity = level >= LOG_FATAL   ? OTLP_SEVERITY_FATAL
                                 : level >= LOG_ERROR ? OTLP_SEVERITY_ERROR
                                 : level >= LOG_WARN  ? OTLP_SEVERITY_WARN
                                 : level >= LOG_INFO  ? OTLP_SEVERITY_INFO
                                 : level >= LOG_DEBUG ? OTLP_SEVERITY_DEBUG
                                                      : OTLP_SEVERITY_TRACE;
      gotel_log(h, severity, body, file, line, function);
    }
    release();
  }
  in_log = false;
}

References args, LOG_DEBUG, LOG_ERROR, LOG_FATAL, LOG_INFO, LOG_WARN, OTEL_BODY_BUFFER_SIZE, safe_vsnprintf(), and url_redact_diagnostic().

Referenced by log_msg().

ascii_otel_metric()

void ascii_otel_metric	(	ascii_otel_metric_t	metric,
		double	value )

Definition at line 161 of file otel.c.

                                                                 {
  gotel_host_t *h = retain();
  if (h) {
    (void)otel_status(gotel_metric_record(h, metric, value), "gotel_metric_record");
    release();
  }
}

Referenced by ascii_otel_frame_rejected(), ascii_otel_pipeline_progress(), crypto_decrypt(), crypto_encrypt(), database_init(), database_session_add_key(), database_session_clear_host(), database_session_join(), database_session_leave(), database_session_lookup(), database_session_revoke_key(), database_session_start_migration(), database_session_update_host(), database_stats_session_count(), database_stats_unique_clients(), discovery_session_apply_handoff(), h265_decode(), h265_encode(), h265_encoder_flush(), mixer_process(), mixer_process_excluding_source(), nat_upnp_open_protocol(), network_connection_open(), opus_codec_decode(), opus_codec_encode(), server_connection_lost(), session_frame_validate_contract(), session_pipeline_run_main(), stats_runtime_packet(), and yt_dlp_extract_with_options().

ascii_otel_packet()

void ascii_otel_packet	(	ascii_otel_scope_t *	scope,
		uint16_t	type,
		size_t	payload_size,
		const char *	action,
		int	transport )

Definition at line 451 of file otel.c.

                                      {
  if (!scope->retained || !scope->scope.span)
    return;
  const char *packet = acip_packet_type_name(type);
  char name[OTEL_NAME_BUFFER_SIZE], version[OTEL_VERSION_BUFFER_SIZE];
  safe_snprintf(name, sizeof(name), "%s.%s", operations[scope->scope.operation].name, packet);
  safe_snprintf(version, sizeof(version), "%d.%d.%d", PROTOCOL_VERSION_MAJOR, PROTOCOL_VERSION_MINOR,
                PROTOCOL_VERSION_PATCH);
  (void)otel_status(otlp_span_set_name(scope->scope.span, name), "otlp_span_set_name");
  gotel_attr_string(&scope->scope, "network.protocol.name", "acip");
  gotel_attr_string(&scope->scope, "network.protocol.version", version);
  gotel_attr_string(&scope->scope, "network.packet.name", packet);
  gotel_attr_int(&scope->scope, "network.packet.type", type);
  gotel_attr_int(&scope->scope, "network.packet.size", (int64_t)payload_size);
  gotel_attr_string(&scope->scope, "network.packet.operation", action);
  const char *carrier = transport == ACIP_TRANSPORT_TCP         ? "tcp"
                        : transport == ACIP_TRANSPORT_WEBSOCKET ? "websocket"
                        : transport == ACIP_TRANSPORT_WEBRTC    ? "webrtc"
                                                                : "unknown";
  gotel_attr_string(&scope->scope, "acip.transport", carrier);
}

References acip_packet_type_name(), ACIP_TRANSPORT_TCP, ACIP_TRANSPORT_WEBRTC, ACIP_TRANSPORT_WEBSOCKET, action, OTEL_NAME_BUFFER_SIZE, OTEL_VERSION_BUFFER_SIZE, PROTOCOL_VERSION_MAJOR, PROTOCOL_VERSION_MINOR, PROTOCOL_VERSION_PATCH, ascii_otel_scope::retained, safe_snprintf(), and ascii_otel_scope::scope.

ascii_otel_pipeline_age()

double ascii_otel_pipeline_age	(	uint64_t	now,
		uint64_t	capture,
		uint64_t	progress,
		bool	expected )

Definition at line 296 of file otel.c.

                                                                                                 {
  return expected && capture && progress && now >= capture && now >= progress && now - capture < 2 * NS_PER_SEC_INT
             ? (double)(now - progress) / 1e9
             : 0;
}

References NS_PER_SEC_INT.

ascii_otel_pipeline_progress()

void ascii_otel_pipeline_progress	(	unsigned	stage,
		unsigned	expected )

Definition at line 270 of file otel.c.

                                                                     {
  if (!ascii_otel_enabled())
    return;
  uint64_t now = time_get_ns();
  if (stage == 0) {
    if (!atomic_load(&pipeline_capture_ns)) {
      atomic_store(&pipeline_display_ns, now);
      atomic_store(&pipeline_encode_ns, now);
    }
    if (!(expected & 1))
      atomic_store(&pipeline_display_ns, now);
    if (!(expected & 2))
      atomic_store(&pipeline_encode_ns, now);
    atomic_store(&pipeline_expected, expected);
    atomic_store(&pipeline_capture_ns, now);
  } else if (stage == 1)
    atomic_store(&pipeline_display_ns, now);
  else if (stage == 2)
    atomic_store(&pipeline_encode_ns, now);
  else {
    atomic_store(&pipeline_expected, 0);
    atomic_store(&pipeline_capture_ns, 0);
    ascii_otel_metric(ASCII_OTEL_METRIC_PIPELINE_DISPLAY_STALL, 0);
    ascii_otel_metric(ASCII_OTEL_METRIC_PIPELINE_ENCODE_STALL, 0);
  }
}

References ascii_otel_enabled(), and ascii_otel_metric().

Referenced by session_pipeline_destroy(), and session_pipeline_run_main().

ascii_otel_scope_begin()

void ascii_otel_scope_begin	(	ascii_otel_scope_t *	s,
		ascii_otel_operation_t	op )

Definition at line 387 of file otel.c.

                                                                              {
  ascii_otel_scope_parent(s, op, NULL);
}

References ascii_otel_scope_parent().

ascii_otel_scope_end()

void ascii_otel_scope_end

(

ascii_otel_scope_t *

s

)

Definition at line 425 of file otel.c.

                                                 {
  if (!s || !s->retained)
    return;
  gotel_end(&s->scope);
  if (current_scope == s)
    current_scope = s->previous;
  s->retained = false;
  release();
}

References ascii_otel_scope::previous, ascii_otel_scope::retained, and ascii_otel_scope::scope.

Referenced by ascii_otel_error_code(), and ascii_otel_frame_rejected().

ascii_otel_scope_int()

void ascii_otel_scope_int	(	ascii_otel_scope_t *	s,
		const char *	key,
		int64_t	value )

Definition at line 728 of file otel.c.

                                                                                 {
  if (s->retained)
    gotel_attr_int(&s->scope, key, value);
}

References ascii_otel_scope::retained, and ascii_otel_scope::scope.

Referenced by session_pipeline_run_main().

ascii_otel_scope_parent()

void ascii_otel_scope_parent	(	ascii_otel_scope_t *	s,
		ascii_otel_operation_t	op,
		const gotel_context_t *	parent )

Definition at line 390 of file otel.c.

                                                                                                              {
  gotel_host_t *h = retain();
  s->retained = h != NULL;
  if (h) {
    gotel_context_t context = gotel_current_context();
    bool lifetime_parent = current_scope && (current_scope->scope.operation == ASCII_OTEL_SESSION_CLIENT_LIKE_RUN ||
                                             current_scope->scope.operation == ASCII_OTEL_SESSION_ATTEMPT);
    // Lifetime spans finish only at shutdown. Completed operations must remain
    // inspectable while a server is running, including after abrupt termination.
    if (!parent && context.valid) {
      gotel_parent_mode_t mode =
          lifetime_parent || memcmp(context.span_id, command_scope.context.span_id, sizeof(context.span_id)) == 0
              ? GOTEL_PARENT_INDEPENDENT
              : GOTEL_PARENT_BOUNDED;
      context = gotel_operation_parent(context, mode);
      parent = &context;
    }
    gotel_begin(h, &s->scope, (size_t)op, parent);
    s->previous = current_scope;
    current_scope = s;
  }
}

References ascii_otel_scope::previous, ascii_otel_scope::retained, and ascii_otel_scope::scope.

Referenced by ascii_otel_scope_begin().

ascii_otel_scope_string()

void ascii_otel_scope_string	(	ascii_otel_scope_t *	s,
		const char *	key,
		const char *	value )

Definition at line 732 of file otel.c.

                                                                                        {
  if (s->retained)
    gotel_attr_string(&s->scope, key, value);
}

References ascii_otel_scope::retained, and ascii_otel_scope::scope.

ascii_otel_shutdown()

void ascii_otel_shutdown

(

void

)

Definition at line 473 of file otel.c.

                               {
  gotel_host_t *h = atomic_ptr_exchange(&host, NULL);
  if (!h)
    return;
  gotel_end(&command_scope);
  uint64_t started = time_get_ns();
  // Leave time for the rest of process teardown, even if the collector stalls.
  uint64_t budget_ns = shutdown_timeout_ns < 400 * NS_PER_MS_INT ? shutdown_timeout_ns : 400 * NS_PER_MS_INT;
  while (atomic_load_explicit(&readers, memory_order_seq_cst) && time_get_ns() - started < budget_ns)
    platform_sleep_ms(1);
  bool producers_active = atomic_load_explicit(&readers, memory_order_seq_cst) != 0;
  atomic_store_explicit(&stopping, true, memory_order_release);
  if (worker_started) {
    while (!atomic_load_explicit(&worker_done, memory_order_acquire) && time_get_ns() - started < budget_ns)
      platform_sleep_ms(1);
    bool done = atomic_load_explicit(&worker_done, memory_order_acquire);
    uint64_t elapsed_ns = time_get_ns() - started;
    int joined = -1;
    if (done && elapsed_ns < budget_ns) {
#if !defined(__linux__) && !defined(_WIN32)
      // The POSIX timed join implementation blocks on these platforms. The worker has
      // finished using the exporter, so detach its remaining wrapper cleanup.
      joined = thread_detach(&worker);
#else
      joined = thread_join_timeout(&worker, NULL, budget_ns - elapsed_ns);
#endif
    }
    if (joined != 0) {
      log_warn("Telemetry worker did not stop within its deadline; exporter retained until process exit");
      return;
    }
    worker_started = false;
  }
  asciichat_error_t result = drain_result;
  otlp_exporter_stats_t stats = {0};
  (void)otel_status(gotel_stats(h, &stats), "gotel_stats");
  // exit() can bypass scope cleanup in a producer. Do not free its host while
  // it remains borrowed; the process will reclaim it after atexit handlers.
  if (!producers_active)
    gotel_destroy(h);
  else
    log_warn("Telemetry producer still active during process shutdown; exporter retained");
  if (result != ASCIICHAT_OK)
    log_warn("Telemetry flush deadline reached; pending records discarded");
  log_debug("Telemetry exporter stopped: spans=%llu/%llu logs=%llu/%llu metrics=%llu/%llu network_errors=%llu "
            "http_4xx=%llu dropped=%llu rejected=%llu",
            (unsigned long long)stats.sent, (unsigned long long)stats.emitted, (unsigned long long)stats.sent_logs,
            (unsigned long long)stats.emitted_logs, (unsigned long long)stats.sent_metrics,
            (unsigned long long)stats.emitted_metrics, (unsigned long long)stats.network_err,
            (unsigned long long)stats.http_4xx, (unsigned long long)(stats.dropped_full + stats.dropped_err),
            (unsigned long long)stats.rejected_spans);
}

References ASCIICHAT_OK, log_debug, log_warn, NS_PER_MS_INT, and platform_sleep_ms().

Referenced by ascii_otel_init(), and main().

ascii_otel_sqlite()

void ascii_otel_sqlite	(	sqlite3 *	db,
		const gotel_query_t *	queries,
		size_t	count )

Definition at line 844 of file otel.c.

                                                                                {
  gotel_host_t *h = retain();
  if (!h)
    return;
  gotel_sqlite_t *a = NULL;
  sequel_analysis_options_t analysis = {.format = true};
  gotel_sqlite_options_t options = {.analysis = &analysis};
  if (otel_status(gotel_sqlite_attach_with_options(h, db, "ascii-chat.storage", queries, count, &options, &a),
                  "Attach SQLite telemetry") != ASCIICHAT_OK)
    log_warn("Could not attach SQLite telemetry");
  release();
}

References ASCIICHAT_OK, and log_warn.

ascii_otel_sqlite_catalog()

void ascii_otel_sqlite_catalog	(	sqlite3 *	db,
		const gotel_query_catalog_t *	catalog )

The catalog accessor and its context must remain valid until the DB closes.

Definition at line 857 of file otel.c.

                                                                                  {
  gotel_host_t *h = retain();
  if (!h)
    return;
  gotel_sqlite_t *a = NULL;
  sequel_analysis_options_t analysis = {.format = true};
  gotel_sqlite_options_t options = {.analysis = &analysis};
  if (otel_status(gotel_sqlite_attach_catalog_with_options(h, db, "ascii-chat.storage", catalog, &options, &a),
                  "Attach SQLite telemetry") != ASCIICHAT_OK)
    log_warn("Could not attach SQLite telemetry");
  release();
}

References ASCIICHAT_OK, and log_warn.

Referenced by database_init().

ascii_otel_sqlite_prepare()

int ascii_otel_sqlite_prepare	(	sqlite3 *	db,
		const char *	sql,
		sqlite3_stmt **	statement )

Prepare NUL-terminated SQL using the attached Gotel policy and SQLite result codes. Unattached databases use ordinary SQLite preparation.

Definition at line 840 of file otel.c.

                                                                                      {
  return gotel_sqlite_prepare_db(db, sql, statement);
}

Referenced by database_init(), database_session_add_key(), database_session_cleanup_expired(), database_session_clear_host(), database_session_find_by_id(), database_session_find_by_string(), database_session_get_keys(), database_session_is_migration_ready(), database_session_leave(), database_session_lookup(), database_session_revoke_key(), database_session_start_migration(), database_session_transport_get(), database_session_transport_set(), database_session_update_host(), database_session_update_host_with_transport(), database_session_verify_key(), database_stats_session_count(), database_stats_snapshot(), and database_stats_unique_clients().

ascii_otel_stats_attach()

void ascii_otel_stats_attach

(

stats_scope_t *

scope

)

Definition at line 218 of file otel.c.

                                                   {
  stats_scope_set_observer(scope, stats_metric_record, NULL);
}

References stats_scope_set_observer().

Referenced by stats_runtime_start().

ascii_otel_stats_metric()

ascii_otel_metric_t ascii_otel_stats_metric	(	stats_record_kind_t	kind,
		unsigned	id )

Definition at line 181 of file otel.c.

                                                                                   {
  if (!((kind == STATS_RECORD_COUNTER && id < STATS_COUNTER_COUNT) ||
        (kind == STATS_RECORD_GAUGE && id < STATS_GAUGE_COUNT) ||
        (kind == STATS_RECORD_DURATION && id < STATS_DURATION_COUNT)))
    return ASCII_OTEL_METRIC_COUNT;
  ascii_otel_metric_t metric;
  switch (((unsigned)kind << 16) | id) {
#define ASCII_STATS_COUNTER(id, metric_id, name, unit)                                                                 \
  case (STATS_RECORD_COUNTER << 16) | STATS_COUNTER_##id:                                                              \
    metric = ASCII_OTEL_METRIC_##metric_id;                                                                            \
    break;
#define ASCII_STATS_GAUGE(id, metric_id, name, unit)                                                                   \
  case (STATS_RECORD_GAUGE << 16) | STATS_GAUGE_##id:                                                                  \
    metric = ASCII_OTEL_METRIC_##metric_id;                                                                            \
    break;
#define ASCII_STATS_DURATION(id, metric_id, name, unit)                                                                \
  case (STATS_RECORD_DURATION << 16) | STATS_DURATION_##id:                                                            \
    metric = ASCII_OTEL_METRIC_##metric_id;                                                                            \
    break;
#include <ascii-chat/stats/telemetry.def>
#undef ASCII_STATS_COUNTER
#undef ASCII_STATS_GAUGE
#undef ASCII_STATS_DURATION
  default:
    return ASCII_OTEL_METRIC_COUNT;
  }
  return metric;
}

References ASCII_OTEL_METRIC_COUNT, STATS_COUNTER_COUNT, STATS_DURATION_COUNT, STATS_GAUGE_COUNT, STATS_RECORD_COUNTER, STATS_RECORD_DURATION, and STATS_RECORD_GAUGE.

ascii_otel_ui_usage()

void ascii_otel_ui_usage	(	const char *	screen,
		const char *	event,
		uint64_t	duration_ns )

Definition at line 434 of file otel.c.

                                                                                      {
  // UI transitions must not inherit realtime media sampling decisions.
  gotel_context_t root = {0};
  ASCII_OTEL_SCOPE_PARENT(UI_USAGE, &root);
  ASCII_OTEL_ATTR_STRING("ascii_chat.ui.screen", screen);
  ASCII_OTEL_ATTR_STRING("ascii_chat.ui.event", event);
  ASCII_OTEL_ATTR_INT("ascii_chat.ui.duration_ns", (int64_t)duration_ns);
}

References ASCII_OTEL_ATTR_INT, ASCII_OTEL_ATTR_STRING, and ASCII_OTEL_SCOPE_PARENT.

Referenced by keyboard_help_toggle_terminal(), log_search_enter_mode(), log_search_exit_mode(), terminal_screen_logs_handle_key_sized(), ui_error_popup_key(), ui_input_media_take(), ui_input_read_key(), update_banner_set_result(), and update_banner_toggle_overlay().