diff --git a/.golangci.yaml b/.golangci.yaml index 11f0577..11522aa 100644 --- a/.golangci.yaml +++ b/.golangci.yaml @@ -39,6 +39,20 @@ linters: - path: ".*\\.pb\\.go$" linters: - lll + - path: '^log/slog\.go$' + linters: + - revive + text: '^(package-comments: should have a package comment|exported: exported function NewPluginLogger should have comment or be unexported)$' + - path: '^log/slog_test\.go$' + linters: + - gosec + text: '^G204: Subprocess launched with variable$' + source: '^\s*cmd := exec\.Command\(executable, "-test\.run=\^TestPluginLoggerProcess\$"\)$' + - path: '^log/slog_test\.go$' + linters: + - gosec + text: '^G204: Subprocess launched with variable$' + source: '^\s*cmd := exec\.Command\(executable, "-test\.run=\^TestReservedAttributeCollisions\$"\)$' settings: cyclop: max-complexity: 8 diff --git a/README.md b/README.md index fd2a581..6b0b667 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,23 @@ API 1.1: `remote_user` owns workspaces; `user` selects the process user. API 1.2 [runtime.proto](proto/devsy/runtime/v1/runtime.proto) specifies RPCs. +## Plugin logging + +Use `log.NewPluginLogger` to write structured provider diagnostics to stderr: + +```go +import pluginlog "github.com/devsy-org/devsy-runtime-sdk/log" + +logger := pluginlog.NewPluginLogger("example") +logger.Info("workspace started", "workspace_id", workspaceID) +``` + +The logger uses newline-delimited JSON with `ts`, `level`, and `msg` fields by default. It adds `component=provider` and the supplied provider name. `DEVSY_LOG_LEVEL` accepts `error`, `warn`, `info`, `debug`, or `trace`, and defaults to `info`. `DEVSY_LOG_FORMAT` accepts `json`, `text`, `plain`, or `auto`. Empty and `auto` select JSON. Invalid values fall back to the defaults and produce a warning without including the invalid value. Configuration is read when each logger is constructed. + +At the root, caller attributes and group names `ts`, `time`, `level`, `msg`, `message`, `component`, and `provider` receive a `user_` prefix. This also applies to attributes in inline groups. Nested named groups retain their original keys. Reserve the `user_` prefix for collision escaping to avoid duplicate keys. + +The logger does not redact application-provided values. Avoid logging secrets. Host-side redaction remains necessary. Logging a fatal severity does not terminate the process. + ## Test and develop Pass `Connect`, `Workspace`, and `Command` to `conformance.Run`. `Command` returns `*runtimev1.ExecStart` with matching `workspace_id`, `tty=false`, and nonempty argv. Map scenarios: diff --git a/log/slog.go b/log/slog.go new file mode 100644 index 0000000..375d762 --- /dev/null +++ b/log/slog.go @@ -0,0 +1,199 @@ +package log + +import ( + "context" + "log/slog" + "os" + "strings" + "time" +) + +func NewPluginLogger(providerName string) *slog.Logger { + level, invalidLevel := pluginLevel(os.Getenv("DEVSY_LOG_LEVEL")) + format := strings.ToLower(os.Getenv("DEVSY_LOG_FORMAT")) + invalidFormat := false + var handler slog.Handler + options := &slog.HandlerOptions{Level: level, ReplaceAttr: replaceEnvelopeAttr} + switch format { + case "", "auto", "json": + handler = slog.NewJSONHandler(os.Stderr, options) + case "text", "plain": + handler = slog.NewTextHandler(os.Stderr, options) + default: + invalidFormat = true + handler = slog.NewJSONHandler(os.Stderr, options) + } + handler = handler.WithAttrs( + []slog.Attr{slog.String("component", "provider"), slog.String("provider", providerName)}, + ) + logger := slog.New(&pluginHandler{handler: handler, root: true}) + if invalidLevel { + _ = logger.Handler(). + Handle(context.Background(), slog.NewRecord(time.Now(), slog.LevelWarn, "invalid DEVSY_LOG_LEVEL; using info", 0)) + } + if invalidFormat { + _ = logger.Handler(). + Handle(context.Background(), slog.NewRecord(time.Now(), slog.LevelWarn, "invalid DEVSY_LOG_FORMAT; using json", 0)) + } + return logger +} + +func pluginLevel(value string) (slog.Level, bool) { + switch strings.ToLower(value) { + case "", "info": + return slog.LevelInfo, false + case "error": + return slog.LevelError, false + case "warn": + return slog.LevelWarn, false + case "debug": + return slog.LevelDebug, false + case "trace": + return slog.Level(-8), false + default: + return slog.LevelInfo, true + } +} + +func replaceEnvelopeAttr(groups []string, attr slog.Attr) slog.Attr { + if len(groups) != 0 { + return attr + } + switch attr.Key { + case slog.TimeKey: + if attr.Value.Kind() == slog.KindTime { + return slog.String("ts", attr.Value.Time().Format("2006-01-02T15:04:05.000Z0700")) + } + case slog.LevelKey: + return replaceLevelAttr(attr) + } + return attr +} + +func replaceLevelAttr(attr slog.Attr) slog.Attr { + level, ok := attr.Value.Any().(slog.Level) + if !ok { + return attr + } + switch level { + case -8: + return slog.String("level", "trace") + case 12: + return slog.String("level", "fatal") + default: + return slog.String("level", strings.ToLower(level.String())) + } +} + +type pluginHandler struct { + handler slog.Handler + root bool +} + +func (h *pluginHandler) Enabled(ctx context.Context, level slog.Level) bool { + return h.handler.Enabled(ctx, level) +} + +func (h *pluginHandler) Handle(ctx context.Context, record slog.Record) error { + if !h.root { + return h.handler.Handle(ctx, record) + } + var replacement slog.Record + changed := false + index := 0 + record.Attrs(func(attr slog.Attr) bool { + escaped, modified := escapeRootAttr(attr) + if modified && !changed { + replacement = slog.NewRecord(record.Time, record.Level, record.Message, record.PC) + copyRecordPrefix(&replacement, record, index) + changed = true + } + if changed { + replacement.AddAttrs(escaped) + } + index++ + return true + }) + if changed { + return h.handler.Handle(ctx, replacement) + } + return h.handler.Handle(ctx, record) +} + +func copyRecordPrefix(dst *slog.Record, src slog.Record, count int) { + src.Attrs(func(attr slog.Attr) bool { + if count == 0 { + return false + } + dst.AddAttrs(attr) + count-- + return true + }) +} + +func (h *pluginHandler) WithAttrs(attrs []slog.Attr) slog.Handler { + if h.root { + attrs, _ = escapeRootAttrs(attrs) + } + return &pluginHandler{handler: h.handler.WithAttrs(attrs), root: h.root} +} + +func (h *pluginHandler) WithGroup(name string) slog.Handler { + if name == "" { + return h + } + if h.root { + name = escapeRootKey(name) + } + return &pluginHandler{handler: h.handler.WithGroup(name)} +} + +func escapeRootKey(key string) string { + switch key { + case "ts", "time", "level", "msg", "message", "component", "provider": + return "user_" + key + default: + return key + } +} + +func escapeRootAttrs(attrs []slog.Attr) ([]slog.Attr, bool) { + var escaped []slog.Attr + for i, attr := range attrs { + value, modified := escapeRootAttr(attr) + if modified && escaped == nil { + escaped = make([]slog.Attr, len(attrs)) + copy(escaped, attrs[:i]) + } + if escaped != nil { + escaped[i] = value + } + } + if escaped == nil { + return attrs, false + } + return escaped, true +} + +func escapeRootAttr(attr slog.Attr) (slog.Attr, bool) { + if attr.Key != "" { + key := escapeRootKey(attr.Key) + if key != attr.Key { + attr.Key = key + return attr, true + } + return attr, false + } + modified := attr.Value.Kind() == slog.KindLogValuer + if modified { + attr.Value = attr.Value.Resolve() + } + if attr.Value.Kind() != slog.KindGroup { + return attr, modified + } + attrs, escaped := escapeRootAttrs(attr.Value.Group()) + if escaped { + attr.Value = slog.GroupValue(attrs...) + } + return attr, modified || escaped +} diff --git a/log/slog_test.go b/log/slog_test.go new file mode 100644 index 0000000..04f8273 --- /dev/null +++ b/log/slog_test.go @@ -0,0 +1,480 @@ +package log_test + +import ( + "bytes" + "context" + "encoding/json" + "log/slog" + "maps" + "os" + "os/exec" + "reflect" + "strings" + "testing" + "time" + + pluginlog "github.com/devsy-org/devsy-runtime-sdk/log" +) + +const ( + infoMessage = "info message" + warnMessage = "warn message" + errorMessage = "error message" + fatalMessage = "fatal message" + debugMessage = "debug message" + traceLevel = "trace" + warnLevel = "warn" + errorLevel = "error" + invalidFormat = "secret-format" + traceMessage = "trace message" + nestedMessage = "nested message" + providerKey = "provider" + messageKey = "msg" + userComponent = "user_component" + userProvider = "user_provider" +) + +type logCase struct { + name string + level string + format string + present []string + absent []string + warnings map[string]int + text bool +} + +type resolvedValue struct{} + +func (resolvedValue) LogValue() slog.Value { + return slog.GroupValue(slog.Int("count", 7), slog.Bool("ready", true)) +} + +type inlineCollisionValue struct{} + +func (inlineCollisionValue) LogValue() slog.Value { + return slog.GroupValue(slog.String("component", "valuer component")) +} + +func TestPluginLoggerProcess(t *testing.T) { + if os.Getenv("DEVSY_TEST_LOG_CHILD") == "1" { + checkLoggerStdout(t, func() { runLogChild(t) }) + return + } + + for _, tc := range append(levelCases(), formatCases()...) { + t.Run(tc.name, func(t *testing.T) { + checkLogCase(t, tc) + }) + } +} + +func levelCases() []logCase { + return []logCase{ + { + name: "defaults", + present: []string{ + infoMessage, + warnMessage, + errorMessage, + fatalMessage, + nestedMessage, + "first remains", + }, + absent: []string{traceMessage, debugMessage, "second filtered"}, + }, + { + name: traceLevel, + level: traceLevel, + present: []string{traceMessage, debugMessage, infoMessage, fatalMessage}, + }, + { + name: "debug", + level: "debug", + present: []string{debugMessage, infoMessage}, + absent: []string{traceMessage}, + }, + { + name: warnLevel, + level: warnLevel, + present: []string{warnMessage, errorMessage}, + absent: []string{traceMessage, debugMessage, infoMessage}, + }, + { + name: errorLevel, + level: errorLevel, + present: []string{errorMessage, fatalMessage}, + absent: []string{warnMessage, infoMessage}, + }, + } +} + +func formatCases() []logCase { + return []logCase{ + { + name: "invalid", + level: "secret-level", + format: invalidFormat, + present: []string{infoMessage}, + absent: []string{"secret-level", invalidFormat, debugMessage}, + warnings: map[string]int{ + "first:invalid DEVSY_LOG_LEVEL; using info": 1, + "first:invalid DEVSY_LOG_FORMAT; using json": 1, + "second:invalid DEVSY_LOG_FORMAT; using json": 1, + }, + }, + { + name: "invalid format above warning threshold", + level: errorLevel, + format: invalidFormat, + present: []string{errorMessage}, + absent: []string{invalidFormat, infoMessage}, + warnings: map[string]int{ + "first:invalid DEVSY_LOG_FORMAT; using json": 1, + "second:invalid DEVSY_LOG_FORMAT; using json": 1, + }, + }, + {name: "auto", format: "auto", present: []string{infoMessage}}, + {name: "json", format: "json", present: []string{infoMessage}}, + { + name: "text", + format: "text", + present: []string{infoMessage, "component=provider", "provider=first"}, + text: true, + }, + { + name: "plain", + format: "plain", + present: []string{infoMessage, "component=provider"}, + text: true, + }, + } +} + +func runLogChild(t *testing.T) { + t.Helper() + logger := pluginlog.NewPluginLogger("first") + logger.Log(context.Background(), slog.Level(-8), traceMessage) + logger.Debug(debugMessage) + logger.Info(infoMessage) + logger.Warn(warnMessage) + logger.Error(errorMessage) + logger.Log(context.Background(), slog.Level(12), fatalMessage) + logger.With("request", 42). + WithGroup("operation"). + Info(nestedMessage, "result", resolvedValue{}) + if err := os.Setenv("DEVSY_LOG_LEVEL", errorLevel); err != nil { + t.Fatal(err) + } + second := pluginlog.NewPluginLogger("second") + second.Info("second filtered") + second.Error("second error") + logger.Info("first remains") +} + +func checkLoggerStdout(t *testing.T, logCalls func()) { + t.Helper() + file, err := os.CreateTemp(t.TempDir(), "logger-stdout-") + if err != nil { + t.Fatal(err) + } + defer func() { _ = file.Close() }() + func() { + original := os.Stdout + os.Stdout = file + defer func() { os.Stdout = original }() + logCalls() + }() + if err := file.Close(); err != nil { + t.Fatal(err) + } + output, err := os.ReadFile(file.Name()) + if err != nil { + t.Fatal(err) + } + if len(output) != 0 { + t.Fatalf("logger wrote to stdout: %q", output) + } +} + +func checkLogCase(t *testing.T, tc logCase) { + t.Helper() + executable, err := os.Executable() + if err != nil { + t.Fatal(err) + } + cmd := exec.Command(executable, "-test.run=^TestPluginLoggerProcess$") + cmd.Env = append( + os.Environ(), + "DEVSY_TEST_LOG_CHILD=1", + "DEVSY_LOG_LEVEL="+tc.level, + "DEVSY_LOG_FORMAT="+tc.format, + ) + var stdout, stderr bytes.Buffer + cmd.Stdout, cmd.Stderr = &stdout, &stderr + if err := cmd.Run(); err != nil { + t.Fatalf("child: %v; stdout: %s; stderr: %s", err, stdout.String(), stderr.String()) + } + output := stderr.String() + checkMessages(t, output, tc) + if !tc.text { + checkJSONRecords(t, output, tc.warnings) + } +} + +func checkMessages(t *testing.T, output string, tc logCase) { + t.Helper() + for _, want := range tc.present { + if !strings.Contains(output, want) { + t.Errorf("missing %q in %s", want, output) + } + } + for _, unwanted := range tc.absent { + if strings.Contains(output, unwanted) { + t.Errorf("unexpected %q in %s", unwanted, output) + } + } +} + +func checkJSONRecords(t *testing.T, output string, expected map[string]int) { + t.Helper() + warnings := make(map[string]int) + for line := range strings.SplitSeq(strings.TrimSpace(output), "\n") { + var record map[string]any + if err := json.Unmarshal([]byte(line), &record); err != nil { + t.Fatalf("invalid JSON %q: %v", line, err) + } + checkEnvelope(t, record) + collectWarning(t, record, warnings) + checkRecord(t, record) + } + if !maps.Equal(warnings, expected) { + t.Errorf("configuration warnings = %v, want %v", warnings, expected) + } +} + +func checkEnvelope(t *testing.T, record map[string]any) { + t.Helper() + ts, ok := record["ts"].(string) + if !ok { + t.Fatalf("missing timestamp: %v", record) + } + if _, err := time.Parse("2006-01-02T15:04:05.000Z0700", ts); err != nil { + t.Errorf("invalid timestamp %q: %v", ts, err) + } + if record["component"] != providerKey || record[providerKey] == nil || + record["level"] == nil || record[messageKey] == nil || record["time"] != nil { + t.Errorf("invalid envelope: %v", record) + } +} + +func collectWarning(t *testing.T, record map[string]any, warnings map[string]int) { + t.Helper() + msg, ok := record[messageKey].(string) + if !ok || !strings.HasPrefix(msg, "invalid DEVSY_LOG_") { + return + } + if record["level"] != warnLevel { + t.Errorf("configuration warning level: %v", record) + } + provider, ok := record[providerKey].(string) + if !ok { + t.Fatalf("invalid warning provider: %v", record) + } + warnings[provider+":"+msg]++ +} + +func checkRecord(t *testing.T, record map[string]any) { + t.Helper() + switch record[messageKey] { + case traceMessage: + checkRecordField(t, record, "level", traceLevel) + case fatalMessage: + checkRecordField(t, record, "level", "fatal") + case nestedMessage: + checkNestedRecord(t, record) + case "second error": + checkRecordField(t, record, providerKey, "second") + case "first remains": + checkRecordField(t, record, providerKey, "first") + } +} + +func checkRecordField(t *testing.T, record map[string]any, key, want string) { + t.Helper() + if record[key] != want { + t.Errorf("%s = %v, want %q: %v", key, record[key], want, record) + } +} + +func checkNestedRecord(t *testing.T, record map[string]any) { + t.Helper() + operation, ok := record["operation"].(map[string]any) + if !ok { + t.Fatalf("missing group: %v", record) + } + result, ok := operation["result"].(map[string]any) + if !ok { + t.Fatalf("missing result: %v", record) + } + ready, ok := result["ready"].(bool) + if !ok || !ready || result["count"] != float64(7) || record["request"] != float64(42) { + t.Errorf("nested attrs: %v", record) + } +} + +func TestReservedAttributeCollisions(t *testing.T) { + if os.Getenv("DEVSY_TEST_COLLISIONS") == "1" { + checkLoggerStdout(t, emitCollisionRecords) + return + } + output := runCollisionChild(t) + want := []map[string]any{ + { + messageKey: "record collision", + "user_ts": float64(1), + "user_time": "caller time", + "user_level": "caller level", + "user_msg": "caller message", + "user_message": true, + userComponent: "caller component", + userProvider: "caller provider", + }, + { + messageKey: "with collision", + userProvider: "with provider", + "user_ts": "with time", + "user_msg": "inline message", + "user_level": float64(7), + userComponent: "valuer component", + "ordinary": float64(9), + }, + { + messageKey: "group collision", + userProvider: map[string]any{ + messageKey: nestedMessage, + "level": float64(2), + "value": true, + }, + }, + { + messageKey: "ordinary group", + userComponent: "with component", + "operation": map[string]any{providerKey: "nested provider", "time": "nested time"}, + }, + } + lines := strings.Split(strings.TrimSpace(output), "\n") + if len(lines) != len(want) { + t.Fatalf("got %d records, want %d: %s", len(lines), len(want), output) + } + for i, line := range lines { + fields := decodeUniqueFields(t, line) + for _, key := range []string{"ts", "level", messageKey, "component", providerKey} { + if _, ok := fields[key]; !ok { + t.Errorf("record %d missing %s: %s", i, key, line) + } + } + checkEnvelope(t, fields) + checkRecordField(t, fields, "level", "info") + checkRecordField(t, fields, "component", providerKey) + checkRecordField(t, fields, providerKey, "original") + for key, value := range want[i] { + if !reflect.DeepEqual(fields[key], value) { + t.Errorf("record %d %s = %v, want %v", i, key, fields[key], value) + } + } + } +} + +func emitCollisionRecords() { + logger := pluginlog.NewPluginLogger("original") + logger.Info( + "record collision", + "ts", + 1, + "time", + "caller time", + "level", + "caller level", + messageKey, + "caller message", + "message", + true, + "component", + "caller component", + providerKey, + "caller provider", + ) + logger.With(providerKey, "with provider", slog.Group("", slog.String("ts", "with time"))). + WithGroup("").Info("with collision", + slog.Group("", slog.String(messageKey, "inline message"), slog.Group("", slog.Int("level", 7))), + slog.Any("", inlineCollisionValue{}), "ordinary", 9) + logger.WithGroup(providerKey). + Info("group collision", messageKey, nestedMessage, "level", 2, "value", true) + logger.With("component", "with component").WithGroup("operation"). + With(providerKey, "nested provider").Info("ordinary group", "time", "nested time") +} + +func runCollisionChild(t *testing.T) string { + t.Helper() + executable, err := os.Executable() + if err != nil { + t.Fatal(err) + } + cmd := exec.Command(executable, "-test.run=^TestReservedAttributeCollisions$") + cmd.Env = append( + os.Environ(), + "DEVSY_TEST_COLLISIONS=1", + "DEVSY_LOG_LEVEL=info", + "DEVSY_LOG_FORMAT=json", + ) + var stdout, stderr bytes.Buffer + cmd.Stdout, cmd.Stderr = &stdout, &stderr + if err := cmd.Run(); err != nil { + t.Fatalf("child: %v; stdout: %s; stderr: %s", err, stdout.String(), stderr.String()) + } + return stderr.String() +} + +func decodeUniqueFields(t *testing.T, line string) map[string]any { + t.Helper() + decoder := json.NewDecoder(strings.NewReader(line)) + open, err := decoder.Token() + if err != nil || open != json.Delim('{') { + t.Fatalf("invalid object %q: %v", line, err) + } + fields := make(map[string]any) + for decoder.More() { + key := uniqueFieldKey(t, decoder, fields, line) + var value any + if err := decoder.Decode(&value); err != nil { + t.Fatalf("invalid value for %q: %v", key, err) + } + fields[key] = value + } + if _, err := decoder.Token(); err != nil { + t.Fatalf("invalid object end: %v", err) + } + return fields +} + +func uniqueFieldKey( + t *testing.T, + decoder *json.Decoder, + fields map[string]any, + line string, +) string { + t.Helper() + token, err := decoder.Token() + if err != nil { + t.Fatalf("invalid key: %v", err) + } + key, ok := token.(string) + if !ok { + t.Fatalf("invalid key: %v", token) + } + if _, exists := fields[key]; exists { + t.Fatalf("duplicate key %q: %s", key, line) + } + return key +}