FAkka.Tracing 0.1.0-alpha1

FAkka.Tracing

FAkka.Tracing is an FP-first F#/.NET tracing toolkit for functions, iterations, and Akka actor incarnations.

Packages

• FAkka.Tracing: Activity-compatible identity, transport-neutral events, sync/Task decorators, sequential iteration tracing, projection, and reports.
• FAkka.Tracing.Akka: Akka.Remote wire serializer, HTTP discovery client, bounded fail-open outbox, and actor restart-incarnation lifecycle adapter.
• FAkka.Tracing.Server: non-packable executable hosting a single-node Akka Cluster collector, Suave Web API, and append-only JSONL store.

Version 0.1.0-alpha1 targets .NET 10 and Akka.NET 1.5.69.

Function Tracing

#r "nuget: FAkka.Tracing, 0.1.0-alpha1"

open System.Threading.Tasks
open FAkka.Tracing

let transport event =
    printfn "%s" (TraceJson.serialize event)
    Task.FromResult { Status = Accepted; Detail = None }

let tracer = Tracer.createDefault "sample" transport

let calculate =
    Trace.decorate tracer "calculate" (fun value -> value * 2)

let result = calculate 21

Use Trace.span or Trace.spanTask when the body needs tags and counters:

let result =
    Trace.span tracer "load-contracts" (fun scope ->
        scope.AddTag("product", "ES")
        scope.AddCounter("files", 1L) |> ignore
        42)

Iteration Tracing

Trace.iter and Trace.iterTask enumerate sequentially once and create zero-based child spans:

Trace.span tracer "definitions" (fun parent ->
    definitionPaths
    |> Trace.iter parent "definition-file" System.IO.Path.GetFileName (fun scope path ->
        scope.AddTag("path", path)
        processDefinition path))

Akka Integration

Add the serializer HOCON from TraceSerialization.hocon to the client ActorSystem, bootstrap discovery once per process, and use RemoteTransport.createOutbox as the Core transport. The instrumentation hot path only calls bounded Channel.TryWrite; HTTP discovery and Akka.Remote Ask run in background work.

Actor lifecycle integration uses:

• ActorLifecycle.beginActorIncarnation before ActorOf.
• ActorLifecycle.registerSpawnedActor after successful creation.
• ActorLifecycle.failActorSpawn when creation fails.
• ActorLifecycle.completeActorTermination from the existing DeathWatch watcher.
• ActorTracingBootstrap.start once per ActorSystem to observe local ActorRestarted events.

No dedicated supervisor or proxy actor is introduced.

Server

dotnet run --project .\src\FAkka.Tracing.Server\FAkka.Tracing.Server.fsproj -c Release -- `
  --web-port 5487 `
  --akka-port 0 `
  --data-path .\data\traces.jsonl

Routes:

• GET /healthz
• GET /api/v1/discovery
• POST /api/v1/traces
• POST /api/v1/spans
• GET /api/v1/traces/{traceId}
• GET /api/v1/reports/{traceId}

The default authorization seam is trusted-network allow-all. Do not expose the alpha server directly to an untrusted network.

Validation

dotnet build .\FAkka.Tracing.slnx -c Release
dotnet run --project .\tests\FAkka.Tracing.Tests\FAkka.Tracing.Tests.fsproj -c Release -- --summary
dotnet run --project .\tests\FAkka.Tracing.Akka.Tests\FAkka.Tracing.Akka.Tests.fsproj -c Release -- --summary
dotnet run --project .\tests\FAkka.Tracing.Server.Tests\FAkka.Tracing.Server.Tests.fsproj -c Release -- --summary

See doc/RUNBOOK.md for operation and doc/SD.md for complete design details.