idlog

README

Navigation >> README English | README Русский | How to Contribute | Как внести вклад в проект

idlog — Structured JSON Logger for Go v1.0.1


A minimal, zero-dependency logger for structured JSON output with readable stack traces.
Built with only the standard library, designed for Yandex Cloud Logging and personal projects.

💡 Part of the id* toolkit by hex21h — simple, explicit, cloud-ready.

✅ Features

• Single-line JSON output
• Log levels: DEBUG, INFO, WARN, ERROR, FATAL
• Global stream_name (1–63 chars) for logical grouping
• Type-driven logging via Log(any):
  • string → INFO
  • error → ERROR (no trace by default)
  • any other type → WARN + embedded function trace
• Debug(message string, enabled bool) — respects debug flag
• Fail(error) → logs FATAL, emits TRACE, exits program
• AddTrace(error) → adds human-readable function trace to an error manually
• Only standard library used: encoding/json, os, runtime, strings, fmt, bytes
• Human-readable trace embedded directly in the message field, showing caller >> callee flow

🚀 Usage

Install

go env -w GOPRIVATE=sourcecraft.dev #needed for private modules
go get sourcecraft.dev/hex21h/idlog@latest

Use in code

package main

import (
	"fmt"

	"sourcecraft.dev/hex21h/idlog"
)

func main() {
	idlog.StreamName = "my-service"

	idlog.Log("Start example")                   //INFO example
	idlog.Log(fmt.Errorf("error"))               //ERROR example (no trace)
	idlog.Log(1)                                 //WARN example (with trace)
	idlog.Debug("debug example", true)           //DEBUG example

	// Manually add trace to errors
	err := fmt.Errorf("some error")
	errWithTrace := idlog.AddTrace(err)
	idlog.Log(errWithTrace)                      //ERROR with manual trace

	idlog.Fail(fmt.Errorf("критическая ошибка")) //FAIL example
}

📤 Output Examples

ERROR + TRACE

{"message":"error | TRACE: main.go:16 +0x78 >> main.main() >> main.go:10 >> main.F1(...) >> idlog.go:68 +0x128","level":"ERROR","stream_name":"my-service"}

DEBUG (enabled)

{"message":"debug example","level":"DEBUG","stream_name":"my-service"}

☁️ Yandex Cloud Logging

• Logs to stdout → automatically captured by YCL.
• Filter by level, stream_name, or message in Yandex UI/CLI.
• No extra setup needed.

📦 Module Info

• No dependencies
• Go 1.21+
• License: MIT

Documentation

Overview

Package idlog provides structured JSON logging with readable stack traces. Designed for Yandex Cloud Logging and standard-library-only environments.

Index

• Constants
• Variables
• func AddTrace(err error) error
• func Debug(message string, enabled bool)
• func Error(err error)
• func Fail(err error)
• func Info(message string)
• func Log(v any)
• func Warn(message string)

Constants

const (
	LevelDebug = "DEBUG"
	LevelInfo  = "INFO"
	LevelWarn  = "WARN"
	LevelError = "ERROR"
	LevelFatal = "FATAL"
)

Variables

var StreamName = "app"

StreamName is the name of the log stream. Must be 1–63 characters. Set it once at application startup.

Functions

func AddTrace

func AddTrace(err error) error

AddTrace adds a human-readable function-only stack trace to an error.

func Debug

func Debug(message string, enabled bool)

Debug logs a DEBUG message only if enabled is true.

func Error

func Error(err error)

Error logs an ERROR message without a function-only stack trace. Use AddTrace function to add a trace manually if needed.

func Fail

func Fail(err error)

Fail logs a FATAL error with a function-only stack trace and exits the program.

func Info

func Info(message string)

Info logs an INFO message.

func Log

func Log(v any)

Log logs based on the type of the argument:

• string → INFO
• error → ERROR (without stack trace)
• other → WARN (with stack trace)

func Warn

func Warn(message string)

Warn logs a WARN message with a function-only stack trace.