Scarf 0.1.1

Scarf .NET SDK

A lightweight, dependency-free-at-runtime .NET client for sending telemetry events to a Scarf Event Collection.

Install

Install the stable release from NuGet:

dotnet add package Scarf --version 0.1.1

Send an event

Create an Event Collection package in Scarf and pass its endpoint to the logger:

using Scarf;

using var logger = new ScarfEventLogger("https://example.gateway.scarf.sh/my-package");
ScarfEventResult result = await logger.LogEventAsync(new { eventName = "startup" });

if (!result.Success)
{
    Console.Error.WriteLine($"Telemetry outcome: {result.Outcome}");
}

Properties are sent as the JSON POST body. Nested objects, arrays, scalar values, null, and an empty object are supported:

await logger.LogEventAsync(new
{
    eventName = "package-resolved",
    package = new { name = "example", version = "1.2.3" },
    features = new[] { "cache", "mirror" },
    optionalValue = (string?)null,
});

The endpoint is used exactly as configured, including existing query parameters. Every request uses Content-Type: application/json.

Timeouts and cancellation

The default timeout is three seconds. Timeouts must be positive and no greater than 49.7 days, the range supported by .NET cancellation timers. Set a constructor default, override one call, or cancel a call independently:

using var logger = new ScarfEventLogger(endpoint, timeout: TimeSpan.FromSeconds(5));
await logger.LogEventAsync(properties, timeout: TimeSpan.FromSeconds(1));

using var cancellation = new CancellationTokenSource();
await logger.LogEventAsync(properties, cancellation.Token);

For managed application lifetimes, inject a shared HttpClient; it is not disposed by default. You can also inject an HttpMessageHandler, which makes tests deterministic and network-free. Ownership is explicit through disposeHttpClient or disposeHandler.

Consent and diagnostics

Set either DO_NOT_TRACK or SCARF_NO_ANALYTICS to 1, true, yes, or on (case-insensitive, surrounding whitespace ignored) to suppress requests. Programmatic disablement is also available:

logger.Enabled = false;

Set SCARF_VERBOSE to a truthy value to opt into diagnostic messages. You can also pass verbose: true. Diagnostics never change request or result behavior.

Results and failure isolation

LogEventAsync does not throw for serialization, timeout, transport, cancellation, or HTTP status failures. ScarfEventResult.Outcome distinguishes:

• Disabled and NotSent;
• Sent for every 2xx response;
• HttpError for non-2xx responses;
• Timeout, TransportError, and Cancelled;
• SerializationError.

ScarfEventResult.WasSent reports whether transport was attempted, including requests cancelled while in flight, so callers can make safe retry decisions. Invalid constructor configuration is rejected immediately. This keeps telemetry failures out of the host application while making outcomes observable.

User-Agent and versioning

Every request identifies the SDK and runtime:

scarf-dotnet/<sdk-version> (platform=<platform>; arch=<architecture>; dotnet=<runtime-version>)

Common platforms are normalized to macOS, linux, and windows. The SDK version comes from assembly/package metadata and falls back to dev only for an unversioned build. The project keeps package, assembly, tag, and User-Agent versions aligned.

Develop

The repository requires the .NET 8 SDK. A fresh clone supports:

dotnet restore dotnet-sdk.sln
dotnet format dotnet-sdk.sln --verify-no-changes --no-restore
dotnet build dotnet-sdk.sln --configuration Release --no-restore
dotnet test dotnet-sdk.sln --configuration Release --no-build
dotnet pack src/Scarf/Scarf.csproj --configuration Release --no-build --output artifacts

The test suite injects HTTP infrastructure and never accesses the network. CI runs the same gates on Ubuntu, macOS, and Windows.

Release

1. Update <Version>, <AssemblyVersion>, and <FileVersion> in src/Scarf/Scarf.csproj.
2. Run the development commands above.
3. Create and push a matching tag, for example git tag v0.1.1 && git push origin v0.1.1.

The tag workflow verifies version consistency, rebuilds, tests, packs deterministic .nupkg and .snupkg artifacts, and attaches them to a GitHub release. It intentionally does not publish to NuGet or contain publishing credentials.

License

Licensed under the Apache License 2.0.