> ## Documentation Index
> Fetch the complete documentation index at: https://docs.westyx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# .NET SDK - Logging

> SDK diagnostics through Microsoft.Extensions.Logging - categories, structured messages, and what is never logged.

Set `NexusConfig.LoggerFactory` to any `Microsoft.Extensions.Logging.ILoggerFactory`.

```csharp theme={null}
await using var client = await NexusClient.CreateAsync(new NexusConfig
{
    BaseUrl       = "https://<slug>.westyx.dev",
    ApiKey        = "wxs_...",
    LoggerFactory = loggerFactory,
});
```

On the [dependency-injection path](https://docs.westyx.dev/sdks/dotnet/dependency-injection.md) this is wired for you - `AddWestyxNexus()` picks up the application's `ILoggerFactory` automatically, so there is nothing to configure:

```csharp theme={null}
builder.Services.AddWestyxNexus(o =>
{
    o.BaseUrl = builder.Configuration["Nexus:BaseUrl"]!;
    o.ApiKey  = builder.Configuration["Nexus:ApiKey"];
});
```

Leaving `LoggerFactory` null discards all SDK output (`NullLoggerFactory`). [`builder.AddWestyxNexus(config)`](https://docs.westyx.dev/sdks/dotnet/package-wiring) creates its client before the application's `ILoggerFactory` exists, so on that path set `NexusConfig.LoggerFactory` to route SDK diagnostics.

The SDK writes nothing on its own: a library logs through the factory the application gives it and falls back to null logging without one, which is [Microsoft's guidance for library authors](https://learn.microsoft.com/dotnet/core/extensions/logging-library-authors). Where and how loudly to log stays the application's decision.

## Seeing what the client loaded

At startup the client logs two `Information` records under `Westyx.Nexus.NexusClient`: the client-ready line, and a summary naming the configs, secrets and flags the first sync delivered - names only, never a value; more than 50 of one kind end in a count.

```
Nexus client ready (key_type=Secret, kind=backend, ttl=00:01:00, wif=off)
Nexus client loaded configs=[DATABASE_URL, FEATURE_LIMIT] secrets=[DB_PASSWORD] flags=[new.checkout]
```

Where they appear depends on how the client is created:

| Path | What to do |
| - | - |
| `builder.Services.AddWestyxNexus(...)` | Nothing - the application's `ILoggerFactory` is used, so both lines are in the application's log. |
| `NexusClient.CreateAsync(config)` | Set `NexusConfig.LoggerFactory`. |
| `builder.AddWestyxNexus(config)` / `builder.Configuration.AddWestyx(config)` | Set `NexusConfig.LoggerFactory`, or set the environment variable below. |

With no `LoggerFactory`, set `WESTYX_NEXUS_LOG_STARTUP=1` (`NexusConfig.LogStartupEnvironmentVariable`) - for example in a pod manifest - and the summary is written to standard error as one line, with no code change:

```
Westyx.Nexus: client loaded configs=[DATABASE_URL, FEATURE_LIMIT] secrets=[DB_PASSWORD] flags=[new.checkout]
```

With a `LoggerFactory` the variable adds nothing; the summary goes through the factory.

A quick console logger for the configuration-source path:

```csharp theme={null}
using var loggerFactory = LoggerFactory.Create(b => b.AddConsole());
builder.AddWestyxNexus(new NexusConfig
{
    BaseUrl       = "https://<slug>.westyx.dev",
    ApiKey        = builder.Configuration["Nexus:ApiKey"],
    LoggerFactory = loggerFactory,
});
```

## Categories

The SDK takes an `ILoggerFactory` rather than an `ILogger<NexusClient>` specifically so it can log under separate categories. That lets you turn one subsystem up without drowning in the others.

| Category | Covers |
| - | - |
| `Westyx.Nexus.NexusClient` | Startup, sync results, file-secret materialisation |
| `Westyx.Nexus.Stream` | SSE connect, reconnect, throttling, transport errors |
| `Westyx.Nexus.Wif` | Workload Identity Federation session exchange and refresh |

```jsonc theme={null}
// appsettings.json - every SSE reconnect, but only sync problems
{
  "Logging": {
    "LogLevel": {
      "Westyx.Nexus.NexusClient": "Warning",
      "Westyx.Nexus.Stream": "Debug",
      "Westyx.Nexus.Wif": "Information"
    }
  }
}
```

## Structured messages

Log statements go through the `LoggerMessage` source generator, so parameters arrive as structured fields rather than being baked into the message text:

```
Sync OK - configs=12 secrets=3 flags=7 key_type=sk kind=backend
    ConfigCount=12  SecretCount=3  FlagCount=7  KeyType=sk  Kind=backend
```

This matters for aggregation. A fixed template with structured parameters means every SSE drop shares one message template, so "how often did the SSE stream drop" is a countable query; interpolating the values into the text would give each occurrence its own unique template.

Each event also carries a stable `EventId`, so you can alert on one specific occurrence without matching on text.

## Secrets never appear in logs

**No SDK log message contains a secret value, an API key or a session JWT** - not even truncated. Key names do appear (the startup summary, an omitted resource); a name is not a value. File-type secrets are identified by a path, never by content.

This is enforced, not merely intended: a test in the suite drives a client through initial sync, a secret read, a file-secret materialisation and a WIF exchange against a capturing logger, and fails the build if any seeded sensitive value appears in the rendered message, the structured state or an exception.

## Logging a `NexusConfig`

`NexusConfig.ApiKey` and `NexusOptions.ApiKey` carry `[JsonIgnore]` and `[IgnoreDataMember]`, so a configuration serialized through System.Text.Json or Newtonsoft.Json contains the base URL and not the key.

**Serilog's destructuring operator honours neither.** `{@Config}` walks public properties directly, so log a config as `{Config}`:

```csharp theme={null}
log.LogInformation("Nexus configured: {Config}", config);   // base URL, no key
log.LogInformation("Nexus configured: {@Config}", config);  // the key is in your log sink
```

The same applies to an options type of your own: a `record` prints its properties from the compiler-generated `ToString()`, so a secret bound into one reaches any log that prints it. Use a `class` for a type that holds a secret.

## Related

* [Dependency injection](https://docs.westyx.dev/sdks/dotnet/dependency-injection.md)
* [Stream observer](https://docs.westyx.dev/sdks/dotnet/stream-observer.md) - structured SSE lifecycle callbacks, complementary to logging
* [Error handling](https://docs.westyx.dev/sdks/dotnet/error-handling.md)
* [Design decisions](https://docs.westyx.dev/sdks/dotnet/design-decisions.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.