viva_tensor - v2.1.0

viva_tensor/telemetry

Observability for viva_tensor.

Structured logging, metrics collection, and statistical benchmarking powered by viva_telemetry. Gives you full visibility into tensor operations, backend selection, memory usage, and gradient computation.

Quick Start

import viva_tensor/telemetry

// Console logging at Info level + all metrics
telemetry.init()

// With JSON file output for production
telemetry.init_with_json("logs/viva_tensor.json")

// Full custom config
telemetry.init_with_config(telemetry.Config(
  log_level: level.Debug,
  json_path: option.Some("logs/tensor.json"),
))

Prometheus Metrics

let metrics_text = telemetry.prometheus()
// Returns all metrics in Prometheus exposition format

Benchmarking

let result = telemetry.benchmark("matmul_100x100", fn() {
  ops.matmul_auto(a, b)
})
telemetry.benchmark_print(result)

Types

Config

</>

Telemetry configuration.

log_level: Minimum severity for log output (default: Info) json_path: Optional path for structured JSON log file

pub type Config {
  Config(
    log_level: level.Level,
    json_path: option.Option(String),
  )
}

Constructors

Values

backend_counter

</> 
pub fn backend_counter(backend: String) -> metrics.Counter

Counter for backend selections (accelerate, zig, erlang).

backward_histogram

</> 
pub fn backward_histogram() -> metrics.Histogram

Histogram for backward pass latency in microseconds.

benchmark

</> 
pub fn benchmark(name: String, f: fn() -> a) -> bench.BenchResult

Run a benchmark with default config (100 warmup, 1000 iterations).

benchmark_all

</> 
pub fn benchmark_all(
  benchmarks: List(#(String, fn() -> a)),
) -> List(bench.BenchResult)

Run multiple benchmarks and return all results.

benchmark_compare

</> 
pub fn benchmark_compare(
  baseline: bench.BenchResult,
  target: bench.BenchResult,
) -> bench.Comparison

Compare two benchmark results. Returns speedup and significance.

benchmark_print

</> 
pub fn benchmark_print(result: bench.BenchResult) -> Nil

Print benchmark result to stdout.

benchmark_print_comparison

</> 
pub fn benchmark_print_comparison(
  comparison: bench.Comparison,
) -> Nil

Print comparison to stdout.

benchmark_table

</> 
pub fn benchmark_table(
  results: List(bench.BenchResult),
) -> String

Convert multiple results to a markdown comparison table.

benchmark_to_markdown

</> 
pub fn benchmark_to_markdown(result: bench.BenchResult) -> String

Convert benchmark result to markdown.

benchmark_with_config

</> 
pub fn benchmark_with_config(
  name: String,
  f: fn() -> a,
  warmup: Int,
  iterations: Int,
) -> bench.BenchResult

Run a benchmark with custom iterations.

default_config

</> 
pub fn default_config() -> Config

Default configuration: Info level, console only.

init

</> 
pub fn init() -> Nil

Initialize telemetry with sensible defaults. Console logging at Info level, all metrics enabled.

init_with_config

</> 
pub fn init_with_config(config: Config) -> Nil

Initialize with full custom configuration.

init_with_json

</> 
pub fn init_with_json(path: String) -> Nil

Initialize with console + JSON file logging. JSON file gets all levels for post-mortem analysis.

log_backend

</> 
pub fn log_backend(backend: String, op: String) -> Nil

Log backend selection at debug level.

log_backward

</> 
pub fn log_backward(num_nodes: Int, duration_us: Int) -> Nil

Log backward pass completion.

log_error

</> 
pub fn log_error(op: String, reason: String) -> Nil

Log a tensor error.

log_matmul

</> 
pub fn log_matmul(
  m: Int,
  k: Int,
  n: Int,
  backend: String,
  duration_us: Int,
) -> Nil

Log matmul execution with performance details.

log_op

</> 
pub fn log_op(op: String, shape: List(Int)) -> Nil

Log a tensor operation at debug level.

log_quantize

</> 
pub fn log_quantize(format: String, ratio: Float) -> Nil

Log quantization operation.

matmul_histogram

</> 
pub fn matmul_histogram() -> metrics.Histogram

Histogram for matmul latency in microseconds.

memory_gauge

</> 
pub fn memory_gauge() -> metrics.Gauge

Gauge for BEAM process memory in bytes.

op_counter

</> 
pub fn op_counter(op: String) -> metrics.Counter

Counter for tensor operations by name.

op_histogram

</> 
pub fn op_histogram() -> metrics.Histogram

Histogram for general operation latency in microseconds.

prometheus

</> 
pub fn prometheus() -> String

Export all collected metrics in Prometheus text format.

quant_counter

</> 
pub fn quant_counter(format: String) -> metrics.Counter

Counter for quantization operations by format.

record_backward

</> 
pub fn record_backward(num_nodes: Int, duration_us: Int) -> Nil

Record a backward pass.

record_dot

</> 
pub fn record_dot(
  size: Int,
  duration_us: Int,
  backend: String,
) -> Nil

Record a dot product operation.

record_matmul

</> 
pub fn record_matmul(
  m: Int,
  n: Int,
  k: Int,
  duration_us: Int,
  backend: String,
) -> Nil

Record a matmul operation with full details.

record_op

</> 
pub fn record_op(op: String, duration_us: Int) -> Nil

Record a generic tensor operation with timing.

record_quantize

</> 
pub fn record_quantize(format: String, ratio: Float) -> Nil

Record a quantization operation.

report_memory

</> 
pub fn report_memory() -> metrics.BeamMemory

Report BEAM memory usage. Logs and records gauge.

✨ Search Document