Observability

Geblang provides lightweight observability modules for scripts, services, tests, and framework code:

• log for structured logging to stdout, stderr, files, or custom handlers.
• metrics for in-process counters, gauges, and simple timings.
• trace for span-style request/workflow traces.
• profile for runtime memory and GC diagnostics.

These modules are intentionally small. They provide useful defaults and clear extension points without requiring a collector, daemon, or external service.

Logging

Import log for structured log entries. A logger is a runtime handle returned by log.stdout, log.stderr, log.file, or log.custom.

import log;

let logger = log.stdout();
log.info(logger, "server started", {"port": 8080});

Built-In Logger Destinations

let out = log.stdout();
let err = log.stderr();
let file = log.file("/var/log/app.log");
defer log.close(file);

log.info(out, "ready");
log.warn(err, "using fallback config", {"path": "config/local.yaml"});
log.error(file, "request failed", {"status": 500, "path": "/api/users"});

Built-in loggers emit one JSON object per line. The exact field order is not part of the API, but entries include at least:

Levels

fields must be a dictionary. Keep fields machine-readable: prefer ids, status codes, durations, paths, and booleans over preformatted message text.

log.info(logger, "user login", {
    "userId": "42",
    "ip": request["remoteAddr"],
    "remember": true
});

log.LogInterface

Custom handlers can implement the exported log.LogInterface. Its required method has this shape:

func handle(string level, string message, dict<string, any> fields): void;

Use it when a class should be accepted by logging-aware code or when you want compile-time checking of the handler shape.

import io;
import json;
import log;

class JsonSink implements log.LogInterface {
    func handle(string level, string message, dict<string, any> fields): void {
        io.println(json.stringify({
            "level": level,
            "message": message,
            "fields": fields
        }));
    }
}

let logger = log.custom(JsonSink());
log.info(logger, "custom logger ready", {"handler": "json"});

log.custom(handler) still checks structurally for a compatible handle method, but implementing log.LogInterface makes the contract explicit:

class MemoryLogger implements log.LogInterface {
    list<dict<string, any>> entries = [];

    func handle(string level, string message, dict<string, any> fields): void {
        this.entries = this.entries.push({
            "level": level,
            "message": message,
            "fields": fields
        });
    }
}

let sink = MemoryLogger();
let logger = log.custom(sink);

log.error(logger, "validation failed", {"field": "email"});
io.println(sink.entries[0]["message"]);

Custom handlers are useful for:

• writing to external services;
• forwarding logs to test assertions;
• adapting logs into framework-specific event systems;
• redacting or transforming fields before output.

Logger Lifecycle

Call log.close(logger) when a logger is no longer needed. File loggers close their underlying file handle. Stdout/stderr/custom loggers unregister the runtime handle.

let file = log.file("app.log");
defer log.close(file);

Do not write to a logger after closing it; the runtime will report an unknown logger handle.

Logging Patterns

Create a request logger:

func logRequest(any logger, dict<string, any> req, int status, int durationMs): void {
    log.info(logger, "http request", {
        "method": req["method"],
        "path": req["path"],
        "status": status,
        "durationMs": durationMs
    });
}

Capture logs in tests:

class Capture implements log.LogInterface {
    list<dict<string, any>> entries = [];

    func handle(string level, string message, dict<string, any> fields): void {
        this.entries = this.entries.push({
            "level": level,
            "message": message,
            "fields": fields
        });
    }
}

let capture = Capture();
let logger = log.custom(capture);
log.warn(logger, "rate limit", {"limit": 100});

io.println(capture.entries.length());

Metrics

Import metrics for process-local counters and gauges. Metric names are free-form strings; use dot-separated names by convention: "http.requests", "jobs.completed", "db.pool.open".

Recording Values

metrics.inc("jobs.completed");
metrics.inc("bytes.sent", 4096);
metrics.set("queue.depth", 12);

Reading Values

let jobs = metrics.get("jobs.completed");
let all = metrics.snapshot();

Timing

let start = metrics.now();
# work
metrics.set("job.durationMs", metrics.duration(start));

Metrics are in-process. Export snapshots to logs, HTTP endpoints, or external collectors when you need persistence.

Trace

Import trace for lightweight span-based tracing. Spans are handles while they are active and dictionaries after snapshot.

Span API

let span = trace.start("load-users");
trace.event(span, "query", {"table": "users"});
trace.event(span, "marshal", {"format": "json"});
trace.end(span);

let spans = trace.snapshot();

Completed span dictionaries contain:

Event dictionaries contain name, fields, and timeUnix.

Profile

Import profile for runtime diagnostics. These helpers are useful for debugging memory-heavy scripts and checking allocation pressure.

Memory Stats

let mem = profile.memStats();
io.println("heap alloc bytes: " + mem["heapAlloc"] as string);
io.println("sys bytes: " + mem["sys"] as string);
io.println("gc cycles: " + mem["numGC"] as string);

Common memStats fields include heapAlloc, heapSys, heapInuse, heapObjects, sys, numGC, and pauseTotalNs.

Timing

let start = profile.now();
# work
let ms = profile.elapsed(start);
io.println("elapsed ms: " + ms as string);

Profiler

Import profiler for precise CPU time and heap measurements from a native Go runtime interface. Use profiler.snapshot() and profiler.delta() together to bracket a section of code, or call profiler.memory() and profiler.cpu() for one-off readings.

This module is always available as a native module and does not require importing from stdlib/.

Functions

peak_alloc tracks the maximum live heap bytes seen across all profiler calls in the process lifetime - equivalent to PHP's memory_get_peak_usage(). It is updated on every call to snapshot(), memory(), and peak().

Example

import profiler;
import io;

let snap = profiler.snapshot();

# do some work
let sum = 0;
for i in range(0, 1000000) {
    sum = sum + i;
}

let d = profiler.delta(snap);
io.println("elapsed: " + d["elapsed_ms"] as string + " ms");
io.println("cpu: " + d["cpu_ms"] as string + " ms");
io.println("heap delta: " + d["heap_alloc"] as string + " bytes");
io.println("allocations: " + d["allocs"] as string + " bytes total");
io.println("gc cycles: " + d["gc_count"] as string);

For a one-off memory check including peak:

import profiler;
import io;

let mem = profiler.memory();
io.println("heap in use: " + mem["heap_alloc"] as string + " bytes");
io.println("peak heap:   " + mem["peak_alloc"] as string + " bytes");
io.println("heap from OS: " + mem["heap_sys"] as string + " bytes");

To check peak memory at the end of a script (similar to memory_get_peak_usage() in PHP):

import profiler;
import io;

# ... script work ...

let p = profiler.peak();
io.println("peak memory: " + p["peak_alloc"] as string + " bytes");