# Logging

Emit one structured ILogger message per executed SQL statement, with the SQL text, parameters and duration. Parameter value capture is opt-in and redactable to protect PII and secrets.

## How logging is wired

When you use the [database context](/database/0.3.2/core-concepts/database-context), the `ILogger` is taken from DI automatically, with no per-call wiring. For code paths that execute SQL through the static API (or to set logging globally), configure the ambient diagnostics once at startup:

```csharp
var app = builder.Build();

SocigyDbDiagnostics.Configure(o =>
{
    o.LoggerFactory = app.Services.GetRequiredService<ILoggerFactory>();
    o.LogLevel = LogLevel.Information;       // default: Debug
    o.CaptureCommandText = true;             // default: true
    o.CaptureParameterValues = false;        // default: false (see below)
});
```

Messages are logged to the category **`Socigy.OpenSource.DB.Sql`** and include the operation, duration in milliseconds, row count, SQL text and parameters as structured properties.

## Parameter value capture is opt-in

By default only parameter **names and DB types** are logged, never the values, because values often contain PII or secrets (passwords, tokens, emails). This mirrors EF Core's `EnableSensitiveDataLogging`.

Enable values explicitly, ideally with a redaction hook and length cap:

```csharp
SocigyDbDiagnostics.Configure(o =>
{
    o.LoggerFactory = loggerFactory;
    o.CaptureParameterValues = true;          // turn values on (non-prod / with redaction)
    o.MaxParameterValueLength = 256;          // truncate long values (default 256)
    o.RedactParameter = (name, value) =>
        name.Contains("password", StringComparison.OrdinalIgnoreCase) ? "***" : value?.ToString();
});
```

> **WARNING** Turning on `CaptureParameterValues` writes raw parameter values to your logs and to the `db.query.parameters` span tag. Only do this in trusted environments and prefer a `RedactParameter` hook.

## Options reference

| Option | Default | Meaning |
|--------|---------|---------|
| `LoggerFactory` | `null` | Source of the logger. `null` disables logging (tracing/metrics unaffected). |
| `CaptureCommandText` | `true` | Include the SQL text in spans and logs. |
| `CaptureParameterValues` | `false` | Include parameter **values** (sensitive). |
| `MaxParameterValueLength` | `256` | Per-value truncation length. |
| `LogLevel` | `Debug` | Level of the per-command message. |
| `RedactParameter` | `null` | `(name, value) => masked` hook, applied when values are captured. |

> **NOTE** A per-context override is also supported: the generated context builds a `DbDiagnosticsContext` from DI, which takes precedence over the ambient `SocigyDbDiagnostics` options for work run through that context.