Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

chore: add task run log context (#20420)

p0ny5a1bc0bb27a9
diff --git a/backend/bin/server/cmd/root.go b/backend/bin/server/cmd/root.go
index 74100f85b6..07730834d1 100644
--- a/backend/bin/server/cmd/root.go
+++ b/backend/bin/server/cmd/root.go
@@ -143,11 +143,14 @@ func checkPort(port int) error {
}
func start() {
+ handlerOptions := &slog.HandlerOptions{AddSource: true, Level: log.LogLevel, ReplaceAttr: log.Replace}
+ var handler slog.Handler
if flags.saas || flags.enableJSONLogging {
- slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{AddSource: true, Level: log.LogLevel, ReplaceAttr: log.Replace})))
+ handler = slog.NewJSONHandler(os.Stdout, handlerOptions)
} else {
- slog.SetDefault(slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{AddSource: true, Level: log.LogLevel, ReplaceAttr: log.Replace})))
+ handler = slog.NewTextHandler(os.Stdout, handlerOptions)
}
+ slog.SetDefault(slog.New(log.NewContextHandler(handler)))
var err error
diff --git a/backend/common/log/context.go b/backend/common/log/context.go
new file mode 100644
index 0000000000..917e0c4527
--- /dev/null
+++ b/backend/common/log/context.go
@@ -0,0 +1,70 @@
+package log //nolint:revive // intentional package name
+
+import (
+ "context"
+ "log/slog"
+)
+
+type contextAttrsKey struct{}
+
+// WithAttrs returns a context carrying slog attributes for context-aware log calls.
+func WithAttrs(ctx context.Context, attrs ...slog.Attr) context.Context {
+ if len(attrs) == 0 {
+ return ctx
+ }
+
+ existingAttrs := attrsFromContext(ctx)
+ replacedKeys := make(map[string]struct{}, len(attrs))
+ for _, attr := range attrs {
+ replacedKeys[attr.Key] = struct{}{}
+ }
+
+ mergedAttrs := make([]slog.Attr, 0, len(existingAttrs)+len(attrs))
+ for _, attr := range existingAttrs {
+ if _, ok := replacedKeys[attr.Key]; ok {
+ continue
+ }
+ mergedAttrs = append(mergedAttrs, attr)
+ }
+ mergedAttrs = append(mergedAttrs, attrs...)
+ return context.WithValue(ctx, contextAttrsKey{}, mergedAttrs)
+}
+
+func attrsFromContext(ctx context.Context) []slog.Attr {
+ if ctx == nil {
+ return nil
+ }
+ attrs, ok := ctx.Value(contextAttrsKey{}).([]slog.Attr)
+ if !ok {
+ return nil
+ }
+ return attrs
+}
+
+type contextHandler struct {
+ handler slog.Handler
+}
+
+// NewContextHandler wraps a slog handler so records include attributes carried by context.
+func NewContextHandler(handler slog.Handler) slog.Handler {
+ return &contextHandler{handler: handler}
+}
+
+func (h *contextHandler) Enabled(ctx context.Context, level slog.Level) bool {
+ return h.handler.Enabled(ctx, level)
+}
+
+func (h *contextHandler) Handle(ctx context.Context, record slog.Record) error {
+ for _, attr := range attrsFromContext(ctx) {
+ record.AddAttrs(attr)
+ }
+ return h.handler.Handle(ctx, record)
+}
+
+func (h *contextHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
+ return &contextHandler{handler: h.handler.WithAttrs(attrs)}
+}
+
+func (h *contextHandler) WithGroup(name string) slog.Handler {
+ return &contextHandler{handler: h.handler.WithGroup(name)}
+}
diff --git a/backend/common/log/context_test.go b/backend/common/log/context_test.go
new file mode 100644
index 0000000000..3f8bc5745e
--- /dev/null
+++ b/backend/common/log/context_test.go
@@ -0,0 +1,38 @@
+package log //nolint:revive // intentional package name
+
+import (
+ "bytes"
+ "context"
+ "log/slog"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+)
+
+func TestContextHandlerAddsAttrsFromContext(t *testing.T) {
+ var buf bytes.Buffer
+ logger := slog.New(NewContextHandler(slog.NewTextHandler(&buf, nil)))
+ ctx := WithAttrs(context.Background(),
+ slog.String("project", "db333"),
+ slog.Int64("task_run_id", 9213),
+ )
+
+ logger.InfoContext(ctx, "migration started")
+
+ output := buf.String()
+ require.Contains(t, output, `msg="migration started"`)
+ require.Contains(t, output, `project=db333`)
+ require.Contains(t, output, `task_run_id=9213`)
+}
+
+func TestContextHandlerSkipsEmptyContext(t *testing.T) {
+ var buf bytes.Buffer
+ logger := slog.New(NewContextHandler(slog.NewTextHandler(&buf, nil)))
+
+ logger.InfoContext(context.Background(), "migration started")
+
+ output := buf.String()
+ require.Contains(t, output, `msg="migration started"`)
+ require.NotContains(t, output, `project=`)
+ require.NotContains(t, output, `task_run_id=`)
+}
diff --git a/backend/component/ghost/config.go b/backend/component/ghost/config.go
index 366588ac91..235608e311 100644
--- a/backend/component/ghost/config.go
+++ b/backend/component/ghost/config.go
@@ -231,7 +231,7 @@ func NewMigrationContext(ctx context.Context, taskID int64, database *store.Data
}
migrationContext := ghostbase.NewMigrationContext()
- migrationContext.Log = newGhostLogger()
+ migrationContext.Log = newGhostLogger(ctx)
migrationContext.InspectorConnectionConfig.Key.Hostname = dataSource.GetHost()
port := 3306
if dataSource.GetPort() != "" {
@@ -311,14 +311,14 @@ func NewMigrationContext(ctx context.Context, taskID int64, database *store.Data
if maxAuthRetries := os.Getenv("GHOST_MAX_AUTH_RETRIES"); maxAuthRetries != "" {
if retries, err := strconv.Atoi(maxAuthRetries); err == nil && retries > 0 {
migrationContext.MaxAuthFailures = retries
- slog.Info("gh-ost auth retry limit set",
+ slog.InfoContext(ctx, "gh-ost auth retry limit set",
slog.Int("max_failures", migrationContext.MaxAuthFailures),
slog.String("source", "environment"))
}
} else {
// Default to 10 retries to prevent retry storms
migrationContext.MaxAuthFailures = 10
- slog.Info("gh-ost auth retry limit set",
+ slog.InfoContext(ctx, "gh-ost auth retry limit set",
slog.Int("max_failures", migrationContext.MaxAuthFailures),
slog.String("source", "default"))
}
diff --git a/backend/component/ghost/config_test.go b/backend/component/ghost/config_test.go
index a2edc29102..be4c4ce189 100644
--- a/backend/component/ghost/config_test.go
+++ b/backend/component/ghost/config_test.go
@@ -1,6 +1,7 @@
package ghost
import (
+ "bytes"
"context"
"crypto/rand"
"crypto/rsa"
@@ -10,6 +11,7 @@ import (
"encoding/pem"
"errors"
"fmt"
+ "log/slog"
"math/big"
"net"
"path/filepath"
@@ -19,10 +21,40 @@ import (
"github.com/stretchr/testify/require"
+ "github.com/bytebase/bytebase/backend/common/log"
storepb "github.com/bytebase/bytebase/backend/generated-go/store"
"github.com/bytebase/bytebase/backend/store"
)
+func TestNewMigrationContextUsesContextAttrs(t *testing.T) {
+ var buf bytes.Buffer
+ prev := slog.Default()
+ t.Cleanup(func() { slog.SetDefault(prev) })
+ slog.SetDefault(slog.New(log.NewContextHandler(slog.NewTextHandler(&buf, nil))))
+ ctx := log.WithAttrs(context.Background(),
+ slog.String("project", "db333"),
+ slog.Int64("task_run_id", 9213),
+ )
+
+ database := &store.DatabaseMessage{DatabaseName: "ghostdb"}
+ dataSource := &storepb.DataSource{
+ Host: "127.0.0.1",
+ Port: "3306",
+ Username: "root",
+ AuthenticationType: storepb.DataSource_PASSWORD,
+ }
+
+ _, cleanup, err := NewMigrationContext(ctx, 1, database, dataSource, "t", "_suffix", "ALTER TABLE t ADD COLUMN c INT", false, nil, 0)
+ require.NoError(t, err)
+ t.Cleanup(cleanup)
+
+ output := buf.String()
+ require.Contains(t, output, `msg="gh-ost auth retry limit set"`)
+ require.Contains(t, output, `project=db333`)
+ require.Contains(t, output, `task_run_id=9213`)
+ require.NotContains(t, output, `replica_id=`)
+}
+
func TestNewMigrationContextWritesTLSMaterialToTempFiles(t *testing.T) {
certPEM, keyPEM := generateSelfSignedPEM(t)
diff --git a/backend/component/ghost/logger.go b/backend/component/ghost/logger.go
index 7255d45d60..e878cffc7c 100644
--- a/backend/component/ghost/logger.go
+++ b/backend/component/ghost/logger.go
@@ -1,6 +1,7 @@
package ghost
import (
+ "context"
"fmt"
"log/slog"
@@ -8,68 +9,73 @@ import (
"github.com/pkg/errors"
)
-type ghostLogger struct{}
+type ghostLogger struct {
+ ctx context.Context
+}
-func newGhostLogger() *ghostLogger {
- return &ghostLogger{}
+func newGhostLogger(ctx context.Context) *ghostLogger {
+ if ctx == nil {
+ ctx = context.Background()
+ }
+ return &ghostLogger{ctx: ctx}
}
-func (*ghostLogger) Debug(args ...any) {
- slog.Debug(fmt.Sprintf(args[0].(string), args[1:]))
+func (l *ghostLogger) Debug(args ...any) {
+ slog.DebugContext(l.ctx, fmt.Sprintf(args[0].(string), args[1:]...))
}
-func (*ghostLogger) Debugf(format string, args ...any) {
- slog.Debug(format, args...)
+func (l *ghostLogger) Debugf(format string, args ...any) {
+ slog.DebugContext(l.ctx, fmt.Sprintf(format, args...))
}
-func (*ghostLogger) Info(args ...any) {
- slog.Info(fmt.Sprintf(args[0].(string), args[1:]))
+func (l *ghostLogger) Info(args ...any) {
+ slog.InfoContext(l.ctx, fmt.Sprintf(args[0].(string), args[1:]...))
}
-func (*ghostLogger) Infof(format string, args ...any) {
- slog.Info(format, args...)
+func (l *ghostLogger) Infof(format string, args ...any) {
+ slog.InfoContext(l.ctx, fmt.Sprintf(format, args...))
}
-func (*ghostLogger) Warning(args ...any) error {
- slog.Warn(fmt.Sprintf(args[0].(string), args[1:]))
+func (l *ghostLogger) Warning(args ...any) error {
+ slog.WarnContext(l.ctx, fmt.Sprintf(args[0].(string), args[1:]...))
return errors.Errorf(args[0].(string), args[1:])
}
-func (*ghostLogger) Warningf(format string, args ...any) error {
- slog.Warn(format, args...)
+func (l *ghostLogger) Warningf(format string, args ...any) error {
+ slog.WarnContext(l.ctx, fmt.Sprintf(format, args...))
return errors.Errorf(format, args...)
}
-func (*ghostLogger) Error(args ...any) error {
- slog.Error(fmt.Sprintf(args[0].(string), args[1:]))
+func (l *ghostLogger) Error(args ...any) error {
+ slog.ErrorContext(l.ctx, fmt.Sprintf(args[0].(string), args[1:]...))
return errors.Errorf(args[0].(string), args[1:])
}
-func (*ghostLogger) Errorf(format string, args ...any) error {
- slog.Error(format, args...)
+func (l *ghostLogger) Errorf(format string, args ...any) error {
+ slog.ErrorContext(l.ctx, fmt.Sprintf(format, args...))
return errors.Errorf(format, args...)
}
-func (*ghostLogger) Errore(err error) error {
+func (l *ghostLogger) Errore(err error) error {
if err != nil {
- slog.Error(err.Error())
+ slog.ErrorContext(l.ctx, err.Error())
}
return err
}
-func (*ghostLogger) Fatal(args ...any) error {
- slog.Error(fmt.Sprintf(args[0].(string), args[1:]))
+func (l *ghostLogger) Fatal(args ...any) error {
+ slog.ErrorContext(l.ctx, fmt.Sprintf(args[0].(string), args[1:]...))
return errors.Errorf(args[0].(string), args[1:])
}
-func (*ghostLogger) Fatalf(format string, args ...any) error {
- slog.Error(format, args...)
+func (l *ghostLogger) Fatalf(format string, args ...any) error {
+ slog.ErrorContext(l.ctx, fmt.Sprintf(format, args...))
return errors.Errorf(format, args...)
}
-func (*ghostLogger) Fatale(err error) error {
+func (l *ghostLogger) Fatale(err error) error {
if err != nil {
- slog.Error(err.Error())
+ slog.ErrorContext(l.ctx, err.Error())
}
return err
}
diff --git a/backend/component/ghost/logger_test.go b/backend/component/ghost/logger_test.go
new file mode 100644
index 0000000000..c46121d987
--- /dev/null
+++ b/backend/component/ghost/logger_test.go
@@ -0,0 +1,32 @@
+package ghost
+
+import (
+ "bytes"
+ "context"
+ "log/slog"
+ "testing"
+
+ "github.com/bytebase/bytebase/backend/common/log"
+
+ "github.com/stretchr/testify/require"
+)
+
+func TestGhostLoggerUsesContextAttrs(t *testing.T) {
+ var buf bytes.Buffer
+ prev := slog.Default()
+ t.Cleanup(func() { slog.SetDefault(prev) })
+ slog.SetDefault(slog.New(log.NewContextHandler(slog.NewTextHandler(&buf, nil))))
+ ctx := log.WithAttrs(context.Background(),
+ slog.String("project", "db333"),
+ slog.Int64("task_run_id", 9213),
+ )
+
+ newGhostLogger(ctx).Infof("Migrating %s.%s", "db_1", "tpri")
+
+ output := buf.String()
+ require.Contains(t, output, `project=db333`)
+ require.Contains(t, output, `task_run_id=9213`)
+ require.NotContains(t, output, `replica_id=`)
+ require.Contains(t, output, `msg="Migrating db_1.tpri"`)
+ require.NotContains(t, output, `!BADKEY`)
+}
diff --git a/backend/runner/taskrun/data_export_executor.go b/backend/runner/taskrun/data_export_executor.go
index 3e05778c33..5f5f2119f3 100644
--- a/backend/runner/taskrun/data_export_executor.go
+++ b/backend/runner/taskrun/data_export_executor.go
@@ -45,7 +45,9 @@ type DataExportExecutor struct {
}
// RunOnce will run the data export task executor once.
-func (exec *DataExportExecutor) RunOnce(ctx context.Context, _ context.Context, task *store.TaskMessage, _ int64) (*storepb.TaskRunResult, error) {
+func (exec *DataExportExecutor) RunOnce(ctx context.Context, _ context.Context, task *store.TaskMessage, taskRunUID int64) (*storepb.TaskRunResult, error) {
+ ctx = taskRunLogContext(ctx, task.ProjectID, taskRunUID)
+
issue, err := exec.store.GetIssue(ctx, &store.FindIssueMessage{ProjectIDs: []string{task.ProjectID}, PlanUID: &task.PlanID})
if err != nil {
return nil, errors.Wrapf(err, "failed to get issue")
@@ -112,11 +114,10 @@ func (exec *DataExportExecutor) RunOnce(ctx context.Context, _ context.Context,
}
bytes, exportErr := exec.executeExport(ctx, instance, database, dataSource, statement, exportConfig.Format, creatorUser)
if exportErr != nil {
- slog.Error("failed to export",
- log.BBError(err),
+ slog.ErrorContext(ctx, "failed to export",
+ log.BBError(exportErr),
slog.String("instance", database.InstanceID),
slog.String("database", database.DatabaseName),
- slog.String("project", database.ProjectID),
)
return nil, exportErr
}
@@ -189,7 +190,7 @@ func (exec *DataExportExecutor) executeExport(
queryCtx := ctx
if queryContext.Timeout != nil {
timeout := queryContext.Timeout.AsDuration()
- slog.Debug("create query context with timeout", slog.Duration("timeout", timeout))
+ slog.DebugContext(ctx, "create query context with timeout", slog.Duration("timeout", timeout))
newCtx, cancelCtx := context.WithTimeout(ctx, timeout)
defer cancelCtx()
queryCtx = newCtx
@@ -207,7 +208,7 @@ func (exec *DataExportExecutor) executeExport(
if err != nil {
return nil, errors.Wrap(err, "failed to execute query")
}
- slog.Debug("execute success", slog.String("instance", instance.ResourceID), slog.String("statement", statement), slog.Duration("duration", time.Since(start)))
+ slog.DebugContext(ctx, "execute success", slog.String("instance", instance.ResourceID), slog.String("statement", statement), slog.Duration("duration", time.Since(start)))
// 5. Format and zip results (NO MASKING)
return exec.formatAndZipResults(ctx, results, instance, database, format, statement)
@@ -220,7 +221,7 @@ func (exec *DataExportExecutor) getSQLResultSizeLimit(
) int64 {
maximumResultSize, err := exec.store.GetSQLResultSize(ctx, workspace)
if err != nil {
- slog.Error("failed to get the sql result size limit", log.BBError(err))
+ slog.ErrorContext(ctx, "failed to get the sql result size limit", log.BBError(err))
return common.DefaultMaximumSQLResultSize
}
return maximumResultSize
@@ -233,7 +234,7 @@ func (exec *DataExportExecutor) getQueryTimeoutInSeconds(
) int64 {
timeout, err := exec.store.GetQueryTimeoutInSeconds(ctx, workspace)
if err != nil {
- slog.Error("failed to get the sql timeout limit", log.BBError(err))
+ slog.ErrorContext(ctx, "failed to get the sql timeout limit", log.BBError(err))
return math.MaxInt64
}
return timeout
diff --git a/backend/runner/taskrun/database_create_executor.go b/backend/runner/taskrun/database_create_executor.go
index f91675dd4c..695c185b7e 100644
--- a/backend/runner/taskrun/database_create_executor.go
+++ b/backend/runner/taskrun/database_create_executor.go
@@ -33,7 +33,9 @@ type DatabaseCreateExecutor struct {
}
// RunOnce will run the database create task executor once.
-func (exec *DatabaseCreateExecutor) RunOnce(ctx context.Context, driverCtx context.Context, task *store.TaskMessage, _ int64) (*storepb.TaskRunResult, error) {
+func (exec *DatabaseCreateExecutor) RunOnce(ctx context.Context, driverCtx context.Context, task *store.TaskMessage, taskRunUID int64) (*storepb.TaskRunResult, error) {
+ ctx = taskRunLogContext(ctx, task.ProjectID, taskRunUID)
+
sheet, err := exec.store.GetSheetFull(ctx, task.Payload.GetSheetSha256())
if err != nil {
return nil, errors.Wrapf(err, "failed to get sheet: %s", task.Payload.GetSheetSha256())
@@ -75,7 +77,7 @@ func (exec *DatabaseCreateExecutor) RunOnce(ctx context.Context, driverCtx conte
}
// Create database.
- slog.Debug("Start creating database...",
+ slog.DebugContext(ctx, "Start creating database...",
slog.String("instance", instance.Metadata.GetTitle()),
slog.String("database", createConfig.Database),
slog.String("statement", statement),
@@ -122,7 +124,7 @@ func (exec *DatabaseCreateExecutor) RunOnce(ctx context.Context, driverCtx conte
}
if err := exec.schemaSyncer.SyncDatabaseSchema(ctx, database); err != nil {
- slog.Error("failed to sync database schema",
+ slog.ErrorContext(ctx, "failed to sync database schema",
slog.String("instanceName", instance.ResourceID),
slog.String("databaseName", database.DatabaseName),
log.BBError(err),
diff --git a/backend/runner/taskrun/database_migrate_executor.go b/backend/runner/taskrun/database_migrate_executor.go
index 33a7e7c4b3..b610b691f9 100644
--- a/backend/runner/taskrun/database_migrate_executor.go
+++ b/backend/runner/taskrun/database_migrate_executor.go
@@ -53,6 +53,8 @@ type DatabaseMigrateExecutor struct {
// RunOnce will run the database migration task executor once.
func (exec *DatabaseMigrateExecutor) RunOnce(ctx context.Context, driverCtx context.Context, task *store.TaskMessage, taskRunUID int64) (*storepb.TaskRunResult, error) {
+ ctx = taskRunLogContext(ctx, task.ProjectID, taskRunUID)
+
// Fetch instance, database, and project (common to all migration types)
instance, err := exec.store.GetInstanceByResourceID(ctx, task.InstanceID)
if err != nil {
@@ -245,7 +247,7 @@ func (exec *DatabaseMigrateExecutor) runStandardMigration(ctx context.Context, d
}
defer driver.Close(ctx)
- slog.Debug("Start migration...",
+ slog.DebugContext(ctx, "Start migration...",
slog.String("instance", database.InstanceID),
slog.String("database", database.DatabaseName),
slog.String("type", task.Type.String()),
@@ -288,7 +290,7 @@ func (exec *DatabaseMigrateExecutor) runStandardMigration(ctx context.Context, d
syncHistory, err := exec.schemaSyncer.SyncDatabaseSchemaToHistory(ctx, database)
if err != nil {
opts.LogDatabaseSyncEnd(err.Error())
- slog.Error("failed to sync database schema", log.BBError(err))
+ slog.ErrorContext(ctx, "failed to sync database schema", log.BBError(err))
} else {
opts.LogDatabaseSyncEnd("")
update.SyncHistory = &syncHistory
@@ -300,7 +302,7 @@ func (exec *DatabaseMigrateExecutor) runStandardMigration(ctx context.Context, d
update.Status = new(store.ChangelogStatusFailed)
}
if err := exec.store.UpdateChangelog(ctx, update); err != nil {
- slog.Error("failed to update changelog", log.BBError(err))
+ slog.ErrorContext(ctx, "failed to update changelog", log.BBError(err))
}
if migrationErr != nil {
@@ -321,7 +323,7 @@ func executeGhostMigration(ctx context.Context, driverCtx context.Context, task
flags = make(map[string]string)
}
- slog.Debug("Start migration...",
+ slog.DebugContext(ctx, "Start migration...",
slog.String("instance", database.InstanceID),
slog.String("database", database.DatabaseName),
slog.String("type", task.Type.String()),
@@ -373,13 +375,13 @@ func executeGhostMigration(ctx context.Context, driverCtx context.Context, task
)
if _, err := driver.GetDB().ExecContext(cleanupCtx, sql); err != nil {
- slog.Warn("failed to cleanup gh-ost temp tables", log.BBError(err))
+ slog.WarnContext(ctx, "failed to cleanup gh-ost temp tables", log.BBError(err))
}
}()
go func() {
if err := migrator.Migrate(); err != nil {
- slog.Error("failed to run gh-ost migration", log.BBError(err))
+ slog.ErrorContext(ctx, "failed to run gh-ost migration", log.BBError(err))
migrationError <- err
return
}
@@ -400,7 +402,7 @@ func executeGhostMigration(ctx context.Context, driverCtx context.Context, task
abortCtx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()
if sendErr := ghostbase.SendWithContext(abortCtx, migrationContext.PanicAbort, err); sendErr != nil {
- slog.Warn("failed to abort gh-ost migration", log.BBError(sendErr))
+ slog.WarnContext(ctx, "failed to abort gh-ost migration", log.BBError(sendErr))
}
return err
}
@@ -451,7 +453,7 @@ func (exec *DatabaseMigrateExecutor) runGhostMigration(ctx context.Context, driv
syncHistory, err := exec.schemaSyncer.SyncDatabaseSchemaToHistory(ctx, database)
if err != nil {
opts.LogDatabaseSyncEnd(err.Error())
- slog.Error("failed to sync database schema", log.BBError(err))
+ slog.ErrorContext(ctx, "failed to sync database schema", log.BBError(err))
} else {
opts.LogDatabaseSyncEnd("")
update.SyncHistory = &syncHistory
@@ -462,7 +464,7 @@ func (exec *DatabaseMigrateExecutor) runGhostMigration(ctx context.Context, driv
update.Status = new(store.ChangelogStatusFailed)
}
if err := exec.store.UpdateChangelog(ctx, update); err != nil {
- slog.Error("failed to update changelog", log.BBError(err))
+ slog.ErrorContext(ctx, "failed to update changelog", log.BBError(err))
}
if migrationErr != nil {
@@ -532,7 +534,7 @@ func (exec *DatabaseMigrateExecutor) runVersionedRelease(ctx context.Context, dr
for _, file := range release.Payload.Files {
// Skip if already applied
if appliedVersions[file.Version] {
- slog.Info("skipping already applied version",
+ slog.InfoContext(ctx, "skipping already applied version",
slog.String("version", file.Version),
slog.String("database", *task.DatabaseName))
continue
@@ -546,7 +548,7 @@ func (exec *DatabaseMigrateExecutor) runVersionedRelease(ctx context.Context, dr
return nil, errors.Errorf("sheet not found: %s", file.SheetSha256)
}
- slog.Info("executing release file",
+ slog.InfoContext(ctx, "executing release file",
slog.String("version", file.Version),
slog.String("database", *task.DatabaseName),
slog.String("file", file.Path))
@@ -564,7 +566,7 @@ func (exec *DatabaseMigrateExecutor) runVersionedRelease(ctx context.Context, dr
if ghost.IsGhostEnabled(sheet.Statement) {
err = executeGhostMigration(ctx, driverCtx, task, sheet, instance, database, driver, &opts)
} else {
- slog.Debug("Start migration...",
+ slog.DebugContext(ctx, "Start migration...",
slog.String("instance", database.InstanceID),
slog.String("database", database.DatabaseName),
slog.String("type", task.Type.String()),
@@ -605,7 +607,7 @@ func (exec *DatabaseMigrateExecutor) runVersionedRelease(ctx context.Context, dr
syncHistory, err := exec.schemaSyncer.SyncDatabaseSchemaToHistory(ctx, database)
if err != nil {
opts.LogDatabaseSyncEnd(err.Error())
- slog.Error("failed to sync database schema", log.BBError(err))
+ slog.ErrorContext(ctx, "failed to sync database schema", log.BBError(err))
} else {
opts.LogDatabaseSyncEnd("")
update.SyncHistory = &syncHistory
@@ -616,7 +618,7 @@ func (exec *DatabaseMigrateExecutor) runVersionedRelease(ctx context.Context, dr
update.Status = new(store.ChangelogStatusFailed)
}
if err := exec.store.UpdateChangelog(ctx, update); err != nil {
- slog.Error("failed to update changelog", log.BBError(err))
+ slog.ErrorContext(ctx, "failed to update changelog", log.BBError(err))
}
if migrationErr != nil {
@@ -657,7 +659,7 @@ func (exec *DatabaseMigrateExecutor) runDeclarativeRelease(ctx context.Context,
return nil, errors.Errorf("sheet not found: %s", file.SheetSha256)
}
- slog.Info("executing declarative release",
+ slog.InfoContext(ctx, "executing declarative release",
slog.String("version", file.Version),
slog.String("database", *task.DatabaseName),
slog.String("file", file.Path))
@@ -681,7 +683,7 @@ func (exec *DatabaseMigrateExecutor) runDeclarativeRelease(ctx context.Context,
}
defer driver.Close(ctx)
- slog.Debug("Start migration...",
+ slog.DebugContext(ctx, "Start migration...",
slog.String("instance", database.InstanceID),
slog.String("database", database.DatabaseName),
slog.String("type", task.Type.String()),
@@ -734,7 +736,7 @@ func (exec *DatabaseMigrateExecutor) runDeclarativeRelease(ctx context.Context,
syncHistory, err := exec.schemaSyncer.SyncDatabaseSchemaToHistory(ctx, database)
if err != nil {
opts.LogDatabaseSyncEnd(err.Error())
- slog.Error("failed to sync database schema", log.BBError(err))
+ slog.ErrorContext(ctx, "failed to sync database schema", log.BBError(err))
} else {
opts.LogDatabaseSyncEnd("")
update.SyncHistory = &syncHistory
@@ -745,7 +747,7 @@ func (exec *DatabaseMigrateExecutor) runDeclarativeRelease(ctx context.Context,
update.Status = new(store.ChangelogStatusFailed)
}
if err := exec.store.UpdateChangelog(ctx, update); err != nil {
- slog.Error("failed to update changelog", log.BBError(err))
+ slog.ErrorContext(ctx, "failed to update changelog", log.BBError(err))
}
if migrationErr != nil {
diff --git a/backend/runner/taskrun/database_migrate_executor_test.go b/backend/runner/taskrun/database_migrate_executor_test.go
index cb1c65b12d..7c1c8900c3 100644
--- a/backend/runner/taskrun/database_migrate_executor_test.go
+++ b/backend/runner/taskrun/database_migrate_executor_test.go
@@ -8,8 +8,24 @@ import (
"github.com/stretchr/testify/require"
storepb "github.com/bytebase/bytebase/backend/generated-go/store"
+ "github.com/bytebase/bytebase/backend/plugin/db"
+ "github.com/bytebase/bytebase/backend/store"
)
+func TestExecuteGhostMigrationUsesContextLogger(t *testing.T) {
+ requireExecuteGhostMigrationContextSignature(t, executeGhostMigration)
+}
+
+func TestRunExecutorOnceUsesContextLogger(t *testing.T) {
+ requireRunExecutorOnceContextSignature(t, RunExecutorOnce)
+}
+
+func requireExecuteGhostMigrationContextSignature(_ *testing.T, _ func(context.Context, context.Context, *store.TaskMessage, *store.SheetMessage, *store.InstanceMessage, *store.DatabaseMessage, db.Driver, *db.ExecuteOptions) error) {
+}
+
+func requireRunExecutorOnceContextSignature(_ *testing.T, _ func(context.Context, context.Context, Executor, *store.TaskMessage, int64) (*storepb.TaskRunResult, error)) {
+}
+
func TestWrappedContextCanceledMatchesErrorsIs(t *testing.T) {
driverCtx, cancel := context.WithCancel(context.Background())
cancel()
diff --git a/backend/runner/taskrun/executor.go b/backend/runner/taskrun/executor.go
index b6fda23298..0247d1aed4 100644
--- a/backend/runner/taskrun/executor.go
+++ b/backend/runner/taskrun/executor.go
@@ -28,7 +28,7 @@ func RunExecutorOnce(ctx context.Context, driverCtx context.Context, exec Execut
if !ok {
panicErr = errors.Errorf("%v", r)
}
- slog.Error("TaskExecutor PANIC RECOVER", log.BBError(panicErr), log.BBStack("panic-stack"))
+ slog.ErrorContext(ctx, "TaskExecutor PANIC RECOVER", log.BBError(panicErr), log.BBStack("panic-stack"))
result = nil
err = errors.Errorf("TaskExecutor PANIC RECOVER, err: %v", panicErr)
}
diff --git a/backend/runner/taskrun/log_context.go b/backend/runner/taskrun/log_context.go
new file mode 100644
index 0000000000..5a88a81f9b
--- /dev/null
+++ b/backend/runner/taskrun/log_context.go
@@ -0,0 +1,19 @@
+package taskrun
+
+import (
+ "context"
+ "log/slog"
+
+ "github.com/bytebase/bytebase/backend/common/log"
+)
+
+func taskRunLogAttrs(projectID string, taskRunUID int64) []slog.Attr {
+ return []slog.Attr{
+ slog.String("project", projectID),
+ slog.Int64("task_run_id", taskRunUID),
+ }
+}
+
+func taskRunLogContext(ctx context.Context, projectID string, taskRunUID int64) context.Context {
+ return log.WithAttrs(ctx, taskRunLogAttrs(projectID, taskRunUID)...)
+}
diff --git a/backend/runner/taskrun/log_context_test.go b/backend/runner/taskrun/log_context_test.go
new file mode 100644
index 0000000000..ec43134590
--- /dev/null
+++ b/backend/runner/taskrun/log_context_test.go
@@ -0,0 +1,33 @@
+package taskrun
+
+import (
+ "bytes"
+ "context"
+ "log/slog"
+ "testing"
+
+ "github.com/bytebase/bytebase/backend/common/log"
+
+ "github.com/stretchr/testify/require"
+)
+
+func TestTaskRunLogAttrs(t *testing.T) {
+ attrs := taskRunLogAttrs("project-a", 123)
+
+ require.Equal(t, []slog.Attr{
+ slog.String("project", "project-a"),
+ slog.Int64("task_run_id", 123),
+ }, attrs)
+}
+
+func TestTaskRunLogContext(t *testing.T) {
+ var buf bytes.Buffer
+ logger := slog.New(log.NewContextHandler(slog.NewTextHandler(&buf, nil)))
+
+ ctx := taskRunLogContext(context.Background(), "project-a", 123)
+ logger.InfoContext(ctx, "task run started")
+
+ output := buf.String()
+ require.Contains(t, output, `project=project-a`)
+ require.Contains(t, output, `task_run_id=123`)
+}
diff --git a/backend/runner/taskrun/running_scheduler.go b/backend/runner/taskrun/running_scheduler.go
index 70707d3aa4..bc6e44f49c 100644
--- a/backend/runner/taskrun/running_scheduler.go
+++ b/backend/runner/taskrun/running_scheduler.go
@@ -58,8 +58,9 @@ func (s *Scheduler) scheduleRunningTaskRuns(ctx context.Context) error {
}
for _, c := range claimed {
- if err := s.executeTaskRun(ctx, c.ProjectID, c.TaskRunUID, c.TaskUID); err != nil {
- slog.Error("failed to execute task run", slog.Int64("id", c.TaskRunUID), log.BBError(err))
+ taskRunCtx := taskRunLogContext(ctx, c.ProjectID, c.TaskRunUID)
+ if err := s.executeTaskRun(taskRunCtx, c.ProjectID, c.TaskRunUID, c.TaskUID); err != nil {
+ slog.ErrorContext(taskRunCtx, "failed to execute task run", log.BBError(err))
}
}
@@ -78,11 +79,7 @@ func (s *Scheduler) executeTaskRun(ctx context.Context, projectID string, taskRu
// Validate task freshness before execution.
if err := s.validateTaskFreshness(ctx, task); err != nil {
- slog.Warn("task run blocked by drift validation",
- slog.Int64("id", task.ID),
- slog.String("type", task.Type.String()),
- log.BBError(err),
- )
+ slog.WarnContext(ctx, "task run blocked by drift validation", log.BBError(err))
taskRunStatusPatch := &store.TaskRunStatusPatch{
ID: taskRunUID,
ProjectID: task.ProjectID,
@@ -119,13 +116,15 @@ func (s *Scheduler) executeTaskRun(ctx context.Context, projectID string, taskRu
}
func (s *Scheduler) runTaskRunOnce(ctx context.Context, taskRunUID int64, task *store.TaskMessage, executor Executor) {
+ ctx = taskRunLogContext(ctx, task.ProjectID, taskRunUID)
+
defer func() {
if r := recover(); r != nil {
err, ok := r.(error)
if !ok {
err = errors.Errorf("%v", r)
}
- slog.Error("Task scheduler V2 runTaskRunOnce PANIC RECOVER", log.BBError(err), log.BBStack("panic-stack"))
+ slog.ErrorContext(ctx, "Task scheduler V2 runTaskRunOnce PANIC RECOVER", log.BBError(err), log.BBStack("panic-stack"))
}
}()
taskRunRef := bus.TaskRunRef{ProjectID: task.ProjectID, ID: taskRunUID}
@@ -140,11 +139,7 @@ func (s *Scheduler) runTaskRunOnce(ctx context.Context, taskRunUID int64, task *
result, err := RunExecutorOnce(ctx, driverCtx, executor, task, taskRunUID)
if err != nil && errors.Is(err, context.Canceled) {
- slog.Warn("task run is canceled",
- slog.Int64("id", task.ID),
- slog.String("type", task.Type.String()),
- log.BBError(err),
- )
+ slog.WarnContext(ctx, "task run is canceled", log.BBError(err))
taskRunStatusPatch := &store.TaskRunStatusPatch{
ID: taskRunUID,
ProjectID: task.ProjectID,
@@ -159,21 +154,14 @@ func (s *Scheduler) runTaskRunOnce(ctx context.Context, taskRunUID int64, task *
if common.ErrorCode(err) == common.Conflict {
return
}
- slog.Error("Failed to mark task as CANCELED",
- slog.Int64("id", task.ID),
- log.BBError(err),
- )
+ slog.ErrorContext(ctx, "Failed to mark task as CANCELED", log.BBError(err))
return
}
return
}
if err != nil {
- slog.Warn("task run failed",
- slog.Int64("id", task.ID),
- slog.String("type", task.Type.String()),
- log.BBError(err),
- )
+ slog.WarnContext(ctx, "task run failed", log.BBError(err))
taskRunStatusPatch := &store.TaskRunStatusPatch{
ID: taskRunUID,
ProjectID: task.ProjectID,
@@ -190,25 +178,26 @@ func (s *Scheduler) runTaskRunOnce(ctx context.Context, taskRunUID int64, task *
if common.ErrorCode(err) == common.Conflict {
return
}
- slog.Error("Failed to mark task as FAILED",
- slog.Int64("id", task.ID),
- log.BBError(err),
- )
+ slog.ErrorContext(ctx, "Failed to mark task as FAILED", log.BBError(err))
return
}
// Immediately try to send PIPELINE_FAILED webhook (HA-safe atomic claim)
claimed, err := s.store.ClaimPipelineFailureNotification(ctx, task.ProjectID, task.PlanID)
if err != nil {
- slog.Error("failed to claim pipeline failure notification", log.BBError(err))
+ slog.ErrorContext(ctx, "failed to claim pipeline failure notification", log.BBError(err))
} else if claimed {
// Get plan and project for webhook
plan, err := s.store.GetPlan(ctx, &store.FindPlanMessage{ProjectID: task.ProjectID, UID: &task.PlanID})
- if err != nil || plan == nil {
- slog.Error("failed to get plan for failure webhook", log.BBError(err))
+ if err != nil {
+ slog.ErrorContext(ctx, "failed to get plan for failure webhook", log.BBError(err))
+ } else if plan == nil {
+ slog.ErrorContext(ctx, "failed to get plan for failure webhook", log.BBError(errors.New("plan not found")))
} else {
- if project, err := s.store.GetProjectByResourceID(ctx, plan.ProjectID); err != nil || project == nil {
- slog.Error("failed to get project for failure webhook", log.BBError(err))
+ if project, err := s.store.GetProjectByResourceID(ctx, plan.ProjectID); err != nil {
+ slog.ErrorContext(ctx, "failed to get project for failure webhook", log.BBError(err))
+ } else if project == nil {
+ slog.ErrorContext(ctx, "failed to get project for failure webhook", log.BBError(errors.New("project not found")))
} else {
// Send PIPELINE_FAILED webhook
s.webhookManager.CreateEvent(ctx, &webhook.Event{
@@ -240,10 +229,7 @@ func (s *Scheduler) runTaskRunOnce(ctx context.Context, taskRunUID int64, task *
if common.ErrorCode(err) == common.Conflict {
return
}
- slog.Error("Failed to mark task as DONE",
- slog.Int64("id", task.ID),
- log.BBError(err),
- )
+ slog.ErrorContext(ctx, "Failed to mark task as DONE", log.BBError(err))
return
}
diff --git a/docs/superpowers/plans/2026-05-27-task-run-log-context.md b/docs/superpowers/plans/2026-05-27-task-run-log-context.md
new file mode 100644
index 0000000000..dcfc674e4d
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-27-task-run-log-context.md
@@ -0,0 +1,144 @@
+# Task Run Log Context Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add consistent structured task-run log context for backend task-run execution logs.
+
+**Architecture:** Store task-run log fields as metadata in `context.Context`, and wrap the configured `slog.Handler` so `slog.*Context` calls append those fields. Task-run code derives a task-run context with `project` and `task_run_id`; gh-ost receives the same context through its existing migration context path.
+
+**Tech Stack:** Go, `log/slog`, existing Bytebase task-run scheduler, `stretchr/testify` for focused unit tests.
+
+---
+
+## File Structure
+
+- Create `backend/common/log/context.go`
+ - Owns generic context-carried slog attributes and a handler wrapper.
+- Create `backend/common/log/context_test.go`
+ - Verifies `InfoContext` records include context attributes.
+- Modify `backend/bin/server/cmd/root.go`
+ - Wraps the configured text or JSON slog handler with `log.NewContextHandler`.
+- Modify `backend/runner/taskrun/log_context.go`
+ - Owns task-run log attributes and `taskRunLogContext`.
+- Modify `backend/runner/taskrun/running_scheduler.go`
+ - Derives task-run contexts at scheduling and execution boundaries.
+- Modify task-run executors in `backend/runner/taskrun`
+ - Uses `slog.*Context` instead of passing scoped loggers.
+- Modify `backend/component/ghost`
+ - Makes the gh-ost logger adapter hold `context.Context` and log through `slog.*Context`.
+- Modify `backend/runner/plancheck/ghost_sync_executor.go`
+ - Uses the simplified gh-ost migration context signature.
+
+No database, proto, frontend, or persisted execution state changes.
+
+### Task 1: Add Context-Aware Slog Handler
+
+**Files:**
+- Create: `backend/common/log/context_test.go`
+- Create: `backend/common/log/context.go`
+- Modify: `backend/bin/server/cmd/root.go`
+
+- [ ] **Step 1: Write failing tests for context log attributes**
+
+Add tests that create a logger with `log.NewContextHandler`, add `project` and `task_run_id` through `log.WithAttrs`, and assert `logger.InfoContext(ctx, ...)` emits those fields.
+
+- [ ] **Step 2: Verify the tests fail**
+
+Run:
+
+```bash
+go test -v -count=1 ./backend/common/log -run '^(TestContextHandlerAddsAttrsFromContext|TestContextHandlerSkipsEmptyContext)$'
+```
+
+Expected: FAIL because `NewContextHandler` and `WithAttrs` do not exist.
+
+- [ ] **Step 3: Implement context attrs and handler wrapper**
+
+Implement `WithAttrs(ctx, attrs...)` and `NewContextHandler(handler)` in `backend/common/log/context.go`. `Handle` should append attributes from context to each slog record.
+
+- [ ] **Step 4: Wire the handler at startup**
+
+In `backend/bin/server/cmd/root.go`, create the text or JSON handler as before, then call:
+
+```go
+slog.SetDefault(slog.New(log.NewContextHandler(handler)))
+```
+
+### Task 2: Move Task-Run Log Context Into Context
+
+**Files:**
+- Modify: `backend/runner/taskrun/log_context.go`
+- Modify: `backend/runner/taskrun/running_scheduler.go`
+- Modify: `backend/runner/taskrun/executor.go`
+- Modify: task-run executor files that log task-run events
+
+- [ ] **Step 1: Write failing tests for task-run context**
+
+Add a test that derives `ctx := taskRunLogContext(context.Background(), "project-a", 123)` and verifies a context-aware slog call emits `project=project-a` and `task_run_id=123`.
+
+- [ ] **Step 2: Implement `taskRunLogContext`**
+
+Keep `taskRunLogAttrs`, and add:
+
+```go
+func taskRunLogContext(ctx context.Context, projectID string, taskRunUID int64) context.Context {
+ return log.WithAttrs(ctx, taskRunLogAttrs(projectID, taskRunUID)...)
+}
+```
+
+- [ ] **Step 3: Replace scoped logger plumbing**
+
+Derive task-run context at scheduler and executor boundaries, then replace task-run-scoped `logger.Warn/Error/Info/Debug` calls with `slog.WarnContext`, `slog.ErrorContext`, `slog.InfoContext`, or `slog.DebugContext`.
+
+### Task 3: Make gh-ost Use Context Log Fields
+
+**Files:**
+- Modify: `backend/component/ghost/logger.go`
+- Modify: `backend/component/ghost/config.go`
+- Modify: `backend/runner/taskrun/database_migrate_executor.go`
+- Modify: `backend/runner/plancheck/ghost_sync_executor.go`
+
+- [ ] **Step 1: Write failing gh-ost context tests**
+
+Add tests that install a context-aware default slog handler, pass a context with `project` and `task_run_id`, and assert gh-ost logs include those fields and format messages without `!BADKEY`.
+
+- [ ] **Step 2: Update gh-ost logger adapter**
+
+Change `ghostLogger` to hold `context.Context` and call `slog.*Context`.
+
+- [ ] **Step 3: Simplify `NewMigrationContext`**
+
+Remove the `*slog.Logger` parameter. Use the received context for both `migrationContext.Log` and gh-ost configuration logs.
+
+### Task 4: Verify
+
+**Files:**
+- Validate all modified Go files and docs.
+
+- [ ] **Step 1: Format**
+
+Run `gofmt -w` on modified Go files.
+
+- [ ] **Step 2: Run focused tests**
+
+Run:
+
+```bash
+go test -v -count=1 ./backend/common/log ./backend/component/ghost ./backend/runner/taskrun ./backend/runner/plancheck
+```
+
+- [ ] **Step 3: Run lint**
+
+Run:
+
+```bash
+golangci-lint run --allow-parallel-runners
+```
+
+- [ ] **Step 4: Run backend build**
+
+Run:
+
+```bash
+go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go
+```
diff --git a/docs/superpowers/specs/2026-05-27-task-run-log-context-design.md b/docs/superpowers/specs/2026-05-27-task-run-log-context-design.md
new file mode 100644
index 0000000000..a29eaae94a
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-27-task-run-log-context-design.md
@@ -0,0 +1,94 @@
+# Task Run Log Context Design
+
+## Goal
+
+Make backend task-run execution easier to trace in Bytebase server logs by adding consistent structured log fields around task-run scheduling and execution.
+
+The first phase focuses on tracing one task run across backend logs. End-to-end request-to-async execution tracing is valid future work, but it is out of scope for this design.
+
+## Current Context
+
+Bytebase backend logging already uses Go `log/slog`, configured at server startup with text or JSON handlers. Existing logs often attach ad hoc fields, but task-run execution logs use ambiguous keys such as `id`, where the value may be a task ID in one message and a task-run ID in another.
+
+Task-run execution flows through `backend/runner/taskrun/running_scheduler.go`:
+
+- `scheduleRunningTaskRuns` claims available task runs.
+- `executeTaskRun` loads the task, validates freshness, updates `started_at`, and starts asynchronous execution.
+- `runTaskRunOnce` runs the executor and updates the final task-run status.
+
+Executors receive `context.Context` and `taskRunUID`, so they can attach the same log context without changing persisted state.
+
+## Approach
+
+Store task-run log attributes in `context.Context`, and wrap the configured `slog.Handler` so context-aware slog calls append those attributes.
+
+Add a small helper in `backend/common/log` for context-carried slog attributes:
+
+- `WithAttrs(ctx, attrs...)`
+- `NewContextHandler(handler)`
+
+`NewContextHandler` wraps the text or JSON handler configured at startup. Logs must use `slog.InfoContext`, `slog.WarnContext`, `slog.ErrorContext`, and related context methods to receive the context attributes.
+
+Add a small helper in `backend/runner/taskrun` that stores task-run log attributes from the available execution data. The standard field set is:
+
+- `project`
+- `task_run_id`
+
+At scheduler boundaries, derive a task-run context:
+
+```go
+ctx := taskRunLogContext(ctx, projectID, taskRunUID)
+```
+
+Then use context-aware slog calls for task-run scoped events:
+
+```go
+slog.WarnContext(ctx, "task run blocked by drift validation", log.BBError(err))
+```
+
+Do not put a logger in `context.Context`. The context stores metadata only. This keeps task-run fields compatible with future request or trace IDs and avoids passing `*slog.Logger` through every executor boundary.
+
+For gh-ost, keep its logger adapter but make it hold the task-run context and call `slog.InfoContext`, `slog.WarnContext`, and `slog.ErrorContext`. `ghost.NewMigrationContext` already receives `ctx`, so gh-ost logs can inherit task-run fields without changing gh-ost itself.
+
+## Scope
+
+Update task-run scheduling and execution logs in `backend/runner/taskrun`, especially:
+
+- claim and execute failures
+- task freshness validation failures
+- panic recovery
+- cancellation
+- executor failure
+- task-run status update failures
+- webhook follow-up failures after task-run failure
+
+Where existing logs use ambiguous `id` for the task run, replace it with explicit `task_run_id`. Avoid adding extra task metadata unless a specific log event needs it.
+
+Executor-internal logs should use context-aware slog calls when the task-run context is available. The executor interface remains unchanged.
+
+## Non-Goals
+
+- No database schema changes.
+- No proto changes.
+- No persisted execution correlation ID.
+- No OpenTelemetry integration.
+- No request ID propagation.
+- No logger stored in `context.Context`.
+- No broad logging abstraction rewrite.
+
+## Future Work
+
+Later request-level tracing can add a request or trace ID through HTTP/gRPC middleware and context propagation. That work should coexist with the task-run fields rather than replace them. A future log line may include both `request_id` and `task_run_id` when the relationship is available.
+
+If many executors need richer shared execution state, introduce a small execution context struct. Do not add that interface churn until repeated executor changes justify it.
+
+## Testing
+
+Run normal Go formatting and validation for backend changes:
+
+- `gofmt -w` on modified Go files
+- `golangci-lint run --allow-parallel-runners`
+- relevant task-run tests
+- backend build
+
+Because the change is observability-only, most verification should be compile, lint, and focused task-run test coverage. Add unit tests only if the helper logic becomes non-trivial.