fields

package
v2.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 20, 2026 License: MIT Imports: 0 Imported by: 0

Documentation

Overview

Package fields defines standard log field names used across all GitLab services. Using these constants ensures consistent field naming in structured logs, making it possible to query and correlate events across services in centralised logging infrastructure.

All field names follow the existing GitLab logging conventions and must be replicated across LabKit language implementations (Go, Ruby) to maintain cross-service consistency.

Usage 

import (
	"log/slog"

	"gitlab.com/gitlab-org/labkit/v2/fields"
)

logger.Info("request completed",
	slog.String(fields.CorrelationID, corrID),
	slog.Int(fields.HTTPStatusCode, 200),
	slog.Float64(fields.DurationS, elapsed.Seconds()),
)
Example

Example shows how to use the canonical field name constants with slog. Using shared constants across services keeps field names consistent in Elasticsearch and Kibana dashboards. 

package main

import (
	"context"
	"log/slog"

	"gitlab.com/gitlab-org/labkit/v2/fields"
)

func main() {
	logger := slog.Default()
	logger.LogAttrs(context.Background(), slog.LevelInfo, "request handled",
		slog.String(fields.CorrelationID, "req-abc-123"),
		slog.String(fields.HTTPMethod, "GET"),
		slog.String(fields.HTTPURL, "https://example.com/api/projects"),
		slog.Int(fields.HTTPStatusCode, 200),
		slog.Float64(fields.DurationS, 0.032),
		slog.String(fields.RemoteIP, "203.0.113.42"),
	)
}

Index

Examples

Constants

View Source 
const (
	// CorrelationID Unique identifier for correlating requests across services.
	// Should be present in all log line emissions.
	CorrelationID = "correlation_id"

	// GitLabUserID GitLab user numeric ID.
	GitLabUserID = "gl_user_id"

	// GitLabUserName GitLab username.
	GitLabUserName = "gl_user_name"

	// DuoWorkflowDefinition Duo Workflow definition identifier (e.g.
	// "analytics_agent/v1"). Identifies which Duo Workflow agent originated a
	// request, enabling per-agent filtering in Kibana and Grafana.
	DuoWorkflowDefinition = "duo_workflow_definition"

	// ErrorType Error type or classification (e.g. "NoMethodError",
	// "ValidationError").
	ErrorType = "error_type"

	// ErrorMessage Detailed error message (e.g. "undefined method 'boom!' for
	// nil").
	ErrorMessage = "error_message"

	// HTTPStatusCode HTTP response status code.
	HTTPStatusCode = "status"

	// HTTPMethod HTTP method (e.g. "GET", "POST").
	HTTPMethod = "method"

	// HTTPURL URL of an HTTP request containing only scheme, host, and path. Query
	// strings and fragments must be omitted to avoid logging sensitive
	// information.
	HTTPURL = "url"

	// DurationS Duration of any operation in seconds. Not limited to HTTP
	// requests; can be used for database queries, background jobs, external API
	// calls. Uses float64 for sub-second precision (e.g. 0.032 for 32ms).
	DurationS = "duration_s"

	// RemoteIP Remote IP address of a request.
	RemoteIP = "remote_ip"

	// TCPAddress TCP address a service is listening on, in "host:port" format
	// (e.g. "0.0.0.0:8080").
	TCPAddress = "tcp_address"

	// HTTPURI Request URI including path and query string with sensitive
	// parameters masked (e.g. "?password=FILTERED").
	HTTPURI = "uri"

	// HTTPHost HTTP Host header of a request (e.g. "api.gitlab.com").
	HTTPHost = "host"

	// HTTPProto HTTP protocol version (e.g. "HTTP/1.1", "HTTP/2.0").
	HTTPProto = "proto"

	// RemoteAddr Raw remote socket address in "host:port" format (e.g.
	// "10.0.0.1:54321"). Use remote_ip when only the IP is needed.
	RemoteAddr = "remote_addr"

	// HTTPReferrer HTTP Referer header with sensitive query parameters masked.
	HTTPReferrer = "referrer"

	// HTTPUserAgent HTTP User-Agent header.
	HTTPUserAgent = "user_agent"

	// WrittenBytes Number of bytes written to the HTTP response body.
	WrittenBytes = "written_bytes"

	// ContentType Content-Type of an HTTP response (e.g. "application/json").
	ContentType = "content_type"

	// TTFBS Time to first byte of an HTTP response in seconds. Measures duration
	// from request receipt to first response byte written.
	TTFBS = "ttfb_s"

	// GitLabProjectID GitLab project numeric ID.
	GitLabProjectID = "gl_project_id"

	// GitLabPipelineID GitLab pipeline numeric ID.
	GitLabPipelineID = "gl_pipeline_id"

	// Timestamp Log event timestamp in ISO 8601 format (e.g.
	// "2026-04-02T12:00:00.000Z").
	Timestamp = "timestamp"

	// Severity Log severity level (e.g. "info", "warn", "error").
	Severity = "severity"

	// LogMessage Human-readable log message describing the event.
	LogMessage = "message"

	// ClassName Class name associated with a log event (e.g. exception class or
	// worker class).
	ClassName = "class_name"

	// ServiceName Name of the service or component emitting the log event.
	ServiceName = "service_name"
)

Field name constants. Each constant holds the canonical log field name as it appears in structured log output.

Variables

View Source 
var Deprecated = map[string]DeprecatedField{

	"tags.correlation_id": {Standard: CorrelationID, ConstantName: "fields.CorrelationID"},

	"user_id":               {Standard: GitLabUserID, ConstantName: "fields.GitLabUserID"},
	"userid":                {Standard: GitLabUserID, ConstantName: "fields.GitLabUserID"},
	"extra.user_id":         {Standard: GitLabUserID, ConstantName: "fields.GitLabUserID"},
	"extra.current_user_id": {Standard: GitLabUserID, ConstantName: "fields.GitLabUserID"},
	"meta.user_id":          {Standard: GitLabUserID, ConstantName: "fields.GitLabUserID"},
	"username":              {Standard: GitLabUserName, ConstantName: "fields.GitLabUserName"},
	"extra.user":            {Standard: GitLabUserName, ConstantName: "fields.GitLabUserName"},
	"meta.user":             {Standard: GitLabUserName, ConstantName: "fields.GitLabUserName"},

	"err":               {Standard: ErrorMessage, ConstantName: "fields.ErrorMessage"},
	"error":             {Standard: ErrorMessage, ConstantName: "fields.ErrorMessage"},
	"error.message":     {Standard: ErrorMessage, ConstantName: "fields.ErrorMessage"},
	"exception.message": {Standard: ErrorMessage, ConstantName: "fields.ErrorMessage"},
	"graphql_errors":    {Standard: ErrorMessage, ConstantName: "fields.ErrorMessage"},

	"status_code":  {Standard: HTTPStatusCode, ConstantName: "fields.HTTPStatusCode"},
	"extra.status": {Standard: HTTPStatusCode, ConstantName: "fields.HTTPStatusCode"},
	"status_text":  {Standard: HTTPStatusCode, ConstantName: "fields.HTTPStatusCode"},
	"http_status":  {Standard: HTTPStatusCode, ConstantName: "fields.HTTPStatusCode"},

	"url":     {Standard: HTTPURL, ConstantName: "fields.HTTPURL"},
	"req_url": {Standard: HTTPURL, ConstantName: "fields.HTTPURL"},

	"duration":        {Standard: DurationS, ConstantName: "fields.DurationS"},
	"duration_ms":     {Standard: DurationS, ConstantName: "fields.DurationS"},
	"elapsed_time":    {Standard: DurationS, ConstantName: "fields.DurationS"},
	"actual_duration": {Standard: DurationS, ConstantName: "fields.DurationS"},
	"time_ms":         {Standard: DurationS, ConstantName: "fields.DurationS"},
	"total_time":      {Standard: DurationS, ConstantName: "fields.DurationS"},
	"gitaly.duration": {Standard: DurationS, ConstantName: "fields.DurationS"},

	"ip":             {Standard: RemoteIP, ConstantName: "fields.RemoteIP"},
	"source_ip":      {Standard: RemoteIP, ConstantName: "fields.RemoteIP"},
	"ip_address":     {Standard: RemoteIP, ConstantName: "fields.RemoteIP"},
	"meta.remote_ip": {Standard: RemoteIP, ConstantName: "fields.RemoteIP"},

	"hostname":        {Standard: HTTPHost, ConstantName: "fields.HTTPHost"},
	"request_host":    {Standard: HTTPHost, ConstantName: "fields.HTTPHost"},
	"gitlab_host":     {Standard: HTTPHost, ConstantName: "fields.HTTPHost"},
	"kubernetes.host": {Standard: HTTPHost, ConstantName: "fields.HTTPHost"},

	"extra.project_id":       {Standard: GitLabProjectID, ConstantName: "fields.GitLabProjectID"},
	"meta.project_id":        {Standard: GitLabProjectID, ConstantName: "fields.GitLabProjectID"},
	"meta.search.project_id": {Standard: GitLabProjectID, ConstantName: "fields.GitLabProjectID"},
	"job_project_id":         {Standard: GitLabProjectID, ConstantName: "fields.GitLabProjectID"},
	"target_project_id":      {Standard: GitLabProjectID, ConstantName: "fields.GitLabProjectID"},

	"extra.pipeline_id": {Standard: GitLabPipelineID, ConstantName: "fields.GitLabPipelineID"},
	"meta.pipeline_id":  {Standard: GitLabPipelineID, ConstantName: "fields.GitLabPipelineID"},
	"root_pipeline_id":  {Standard: GitLabPipelineID, ConstantName: "fields.GitLabPipelineID"},

	"start_time": {Standard: Timestamp, ConstantName: "fields.Timestamp"},

	"level": {Standard: Severity, ConstantName: "fields.Severity"},

	"msg":              {Standard: LogMessage, ConstantName: "fields.LogMessage"},
	"custom_message":   {Standard: LogMessage, ConstantName: "fields.LogMessage"},
	"extra.message":    {Standard: LogMessage, ConstantName: "fields.LogMessage"},
	"fields.message":   {Standard: LogMessage, ConstantName: "fields.LogMessage"},
	"graphql.message":  {Standard: LogMessage, ConstantName: "fields.LogMessage"},
	"reason":           {Standard: LogMessage, ConstantName: "fields.LogMessage"},
	"color_message":    {Standard: LogMessage, ConstantName: "fields.LogMessage"},
	"exception.gitaly": {Standard: LogMessage, ConstantName: "fields.LogMessage"},

	"class":            {Standard: ClassName, ConstantName: "fields.ClassName"},
	"author_class":     {Standard: ClassName, ConstantName: "fields.ClassName"},
	"exception.class":  {Standard: ClassName, ConstantName: "fields.ClassName"},
	"extra.class":      {Standard: ClassName, ConstantName: "fields.ClassName"},
	"extra.class_name": {Standard: ClassName, ConstantName: "fields.ClassName"},

	"service":           {Standard: ServiceName, ConstantName: "fields.ServiceName"},
	"grpc.service_name": {Standard: ServiceName, ConstantName: "fields.ServiceName"},
	"auth_service":      {Standard: ServiceName, ConstantName: "fields.ServiceName"},
	"type":              {Standard: ServiceName, ConstantName: "fields.ServiceName"},
	"component":         {Standard: ServiceName, ConstantName: "fields.ServiceName"},
	"subcomponent":      {Standard: ServiceName, ConstantName: "fields.ServiceName"},
}

Deprecated maps deprecated log field name strings to their canonical replacements. Consumers should use this map to validate field names in their codebase and suggest migrations to the standardised constants defined in this package.

Example: a service logging "user_id" should instead use fields.GitLabUserID ("gl_user_id").

Functions

This section is empty.

Types

type DeprecatedField 

type DeprecatedField struct {
	// Standard is the canonical field value (e.g. "gl_user_id").
	Standard string
	// ConstantName is the Go constant to reference in source (e.g. "fields.GitLabUserID").
	ConstantName string
}

DeprecatedField describes a deprecated log field name and its canonical replacement.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.