Logregistratie en diagnostische gegevens met go-mssqldb

De go-mssqldb driver biedt configureerbare logging voor het oplossen van verbindingsproblemen, queryproblemen en prestatie-analyse. Dit artikel beschrijft de beschikbare logvlaggen en hoe je aangepaste loggers kunt gebruiken.

Logvlaggen

Gebruik de log verbindingsparameter om diagnostische output in te schakelen. Logvlaggen zijn bitmaskwaarden, wat betekent dat je ze kunt combineren door hun gehele waarden op te tellen:

Vlagwaarde	Category	Description
`1`	Errors	Registreer foutmeldingen.
`2`	Messages	Leg informatieberichten van de server vast.
`4`	Rows	Rijgegevens registreren.
`8`	SQL	Log SQL-statements die naar de server zijn gestuurd.
`16`	Parameters	Registreer parameternamen en -waarden.
`32`	Transactions	Registreer gebeurtenissen als het starten van transacties, commit en rollback.
`64`	Debug	Leg protocoldetails op laag niveau en TDS-details vast.
`128`	Hernieuwde pogingen	Nieuwe verbindingspogingen loggen.

Vlaggen 4 (rijen) en 16 (parameters) kunnen applicatiegegevens, geheimen of persoonlijk identificeerbare informatie blootleggen. Behandel ze als kortstondige diagnostische vlaggen, niet als routinematige productieomgevingen.

Examples

Alleen logfouten:

sqlserver://<user>:<password>@<server>?database=AdventureWorks2025&log=1

Logboekfouten, SQL-instructies en parameters:

sqlserver://<user>:<password>@<server>?database=AdventureWorks2025&log=25

Opmerking

De waarde 25 wordt berekend als 1 + 8 + 16 (fouten + SQL + parameters).

Alles loggen:

sqlserver://<user>:<password>@<server>?database=AdventureWorks2025&log=255

Warning

Hoge waarden van logboekvlaggen (64, 128, 255) leveren uitgebreide uitvoer op en kunnen de prestaties beïnvloeden. Gebruik ze alleen voor het debuggen.

Standaardlogger

Standaard logt de driver naar Go's standaardpakket log, dat naar os.Stderr schrijft. De output bevat tijdstempels en de logcategorie:

2026/03/28 10:15:30 mssql: login successful
2026/03/28 10:15:30 mssql: SQL: SELECT 1

Aangepaste logger met SetLogger

Gebruik mssql.SetLogger om de loguitvoer van het stuurprogramma om te leiden naar een aangepaste logger. De logger moet de interface implementeren mssql.Logger :

import "github.com/microsoft/go-mssqldb"

type myLogger struct{}

func (l *myLogger) Printf(format string, v ...interface{}) {
    // Write to your preferred logging system
    fmt.Printf("[MSSQL] "+format+"\n", v...)
}

func (l *myLogger) Println(v ...interface{}) {
    fmt.Println(append([]interface{}{"[MSSQL]"}, v...)...)
}

func main() {
    mssql.SetLogger(&myLogger{})
    // ... open connection
}

Contextbewuste logger met SetContextLogger

Gebruik mssql.SetContextLogger om een contextbewuste logger te bieden. De logger moet de mssql.ContextLogger interface implementeren, die één methode Log heeft die de context, een logcategorie en een berichtstring ontvangt. Met deze aanpak kun je driverlogs koppelen aan aanvraaggebonden tracinggegevens (bijvoorbeeld trace-ID's):

import (
    "context"
    "log/slog"
    "github.com/microsoft/go-mssqldb"
    "github.com/microsoft/go-mssqldb/msdsn"
)

type contextLogger struct{}

func (l *contextLogger) Log(ctx context.Context, category msdsn.Log, msg string) {
    slog.InfoContext(ctx, msg, "category", category)
}

func main() {
    mssql.SetContextLogger(&contextLogger{})
    // ... open connection
}

Controlelijst voor diagnostische gegevens

Bij het oplossen van een verbindings- of queryprobleem:

Start met log=1 voor fouten, of met log=3 als je ook serverberichten nodig hebt.
Reproduceer het probleem en bekijk de fouttekst voordat je meer categorieën inschakelt.
Voeg 8 toe als je wilt bevestigen welke SQL-instructie of procedureaanroep werd verzonden.
Voeg toe 16 of 4 alleen in een veilige omgeving waar parameterwaarden en teruggegeven rijen kunnen worden geregistreerd zonder gevoelige gegevens bloot te stellen.
Als het probleem op protocolniveau lijkt te zitten of met herpogingen te maken heeft, verhoog dan log=64 of voeg 128 toe voor diagnostiek van herpogingen.
Verwijder of verminder het loggen nadat het probleem is opgelost.

Gestructureerde logging met log/slog

Go 1.21 introduceerde log/slog voor gestructureerd loggen. Gebruik SetContextLogger om de uitvoer van het stuurprogramma via slog te leiden:

import (
    "context"
    "log/slog"
    "os"

    "github.com/microsoft/go-mssqldb"
    "github.com/microsoft/go-mssqldb/msdsn"
)

type slogLogger struct {
    logger *slog.Logger
}

func (l *slogLogger) Log(ctx context.Context, category msdsn.Log, msg string) {
    level := slog.LevelInfo
    if category == msdsn.LogErrors {
        level = slog.LevelError
    }
    if category == msdsn.LogDebug {
        level = slog.LevelDebug
    }

    l.logger.LogAttrs(ctx, level, msg,
        slog.Int("category", int(category)),
    )
}

func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        Level: slog.LevelInfo,
    }))

    mssql.SetContextLogger(&slogLogger{logger: logger})

    // Connection logging now produces structured JSON.
}

Integratie met zerolog

Zerolog is een gestructureerde logger met nul-allocatie. Leid driverlogs via zerolog:

import (
    "context"
    "os"

    "github.com/microsoft/go-mssqldb"
    "github.com/microsoft/go-mssqldb/msdsn"
    "github.com/rs/zerolog"
)

type zerologAdapter struct {
    logger zerolog.Logger
}

func (l *zerologAdapter) Log(ctx context.Context, category msdsn.Log, msg string) {
    event := l.logger.Info()
    if category == msdsn.LogErrors {
        event = l.logger.Error()
    }
    event.Int("category", int(category)).Msg(msg)
}

func main() {
    logger := zerolog.New(os.Stdout).With().Timestamp().Logger()
    mssql.SetContextLogger(&zerologAdapter{logger: logger})
}

Integratie met zap

zap is een zeer snelle gestructureerde logger. Rittenregistratie van chauffeurs via Zap:

import (
    "context"

    "github.com/microsoft/go-mssqldb"
    "github.com/microsoft/go-mssqldb/msdsn"
    "go.uber.org/zap"
)

type zapAdapter struct {
    logger *zap.Logger
}

func (l *zapAdapter) Log(ctx context.Context, category msdsn.Log, msg string) {
    if category == msdsn.LogErrors {
        l.logger.Error(msg, zap.Int("category", int(category)))
    } else {
        l.logger.Info(msg, zap.Int("category", int(category)))
    }
}

func main() {
    logger, _ := zap.NewProduction()
    defer logger.Sync()

    mssql.SetContextLogger(&zapAdapter{logger: logger})
}

Doorgifte van correlatie-id

In gedistribueerde systemen wordt een correlatie-ID via de context verspreid zodat driverlogs kunnen worden gecorreleerd met het verzoek dat ze heeft getriggerd:

type correlationKey struct{}

func WithCorrelationID(ctx context.Context, id string) context.Context {
    return context.WithValue(ctx, correlationKey{}, id)
}

func CorrelationID(ctx context.Context) string {
    if id, ok := ctx.Value(correlationKey{}).(string); ok {
        return id
    }
    return "unknown"
}

type correlatedLogger struct {
    logger *slog.Logger
}

func (l *correlatedLogger) Log(ctx context.Context, category msdsn.Log, msg string) {
    l.logger.LogAttrs(ctx, slog.LevelInfo, msg,
        slog.String("correlation_id", CorrelationID(ctx)),
        slog.Int("category", int(category)),
    )
}

Geef vervolgens de correlatie-ID door via de context van je verzoek:

func handleRequest(w http.ResponseWriter, r *http.Request) {
    correlationID := r.Header.Get("X-Correlation-ID")
    if correlationID == "" {
        correlationID = uuid.NewString()
    }

    ctx := WithCorrelationID(r.Context(), correlationID)

    // All database operations using this context will include the correlation ID.
    rows, err := db.QueryContext(ctx, "SELECT TOP (10) ProductID, Name FROM Production.Product")
    // ...
}

Hoe correlatie-ID's in de praktijk te gebruiken

Gebruik correlatie-ID's als een traceersleutel over logs, herhalingen en databaseaanroepen:

Genereer of accepteer een correlatie-ID bij de verzoekgrens.
Sla het op in de request context en neem het op in applicatie- en driverlogs.
Voor probleemopsporing aan de SQL-kant stel je dit in de sessiecontext in met sp_set_session_context en lees je het uit met SESSION_CONTEXT.

Correlatie-ID's worden niet automatisch opgeslagen in SQL Server-tabellen. SESSION_CONTEXT is sessie-scoped, dus waarden gelden alleen voor de huidige verbinding en blijven niet bestaan nadat de sessie is beëindigd.

Als je duurzame geschiedenis nodig hebt, schrijf dan de correlatie-ID expliciet naar je audit- of bedrijfstabellen (bijvoorbeeld een AuditLog tabel met correlation_id, tijdstempel, bewerking en status).

Configuratie van productielogging

In productie kun je minimale logging inschakelen om prestatie-overhead te voorkomen en te voorkomen dat gevoelige gegevens in logs verschijnen:

Milieu	Aanbevolen `log` waarde	Wat wordt vastgelegd
Development	`63` (fouten + berichten + rijen + SQL + params + transacties)	Volledige zichtbaarheid voor debugging.
Staging	`3` (fouten + berichten)	Fouten en serverberichten zonder querydetails.
Productie	`1` (fouten) of `0` (uit)	Alleen fouten, of het volledig uitschakelen van driver-logging.

Let op

De Parameters vlag (16) registreert daadwerkelijke parameterwaarden, die persoonlijk identificeerbare informatie (PII), wachtwoorden of andere gevoelige gegevens kunnen omvatten. Schakel deze vlag nooit in productie in. Voor een volledige risicobeoordeling van elke vlag, zie Security best practices.

Logregistratie in productie onderdrukken

Gebruik omgevingsvariabelen om het logniveau per implementatiefase te regelen:

if os.Getenv("APP_ENV") == "production" {
    // Use only error-level logging in production.
    connString += "&log=1"
} else {
    // Full logging in development.
    connString += "&log=63"
}

Feedback

Is deze pagina nuttig?

Last updated on 2026-07-21