Logging

JSON-structured logs in production, one log file per concern, all enriched with Gitlab::ApplicationContext.

Loggers

Logger	File	Used for
Gitlab::AppLogger	application.log (text)	General app messages
Gitlab::AppJsonLogger	application_json.log	JSON variant of the above
Gitlab::AuditJsonLogger	audit_json.log	Sensitive actions
Gitlab::AuthLogger	auth.log	Auth attempts, token creation
Gitlab::IntegrationsLogger	integrations_json.log	Webhook delivery, integration calls
Gitlab::ImportLogger	importer.log	Project / group imports
Gitlab::GitLogger	git.log	Gitaly client side
Gitlab::DatabaseWarningsLogger	database_load_balancing.log	DB load-balancer warnings
Gitlab::EnvironmentLogger, Gitlab::FileHookLogger, ...	misc per-domain

The Gitlab::Loggable concern provides a common API used in services.

Application context

Every log line includes a JSON object built by Gitlab::ApplicationContext:

• correlation_id — propagated across services and Sidekiq jobs.
• meta.user, meta.project, meta.root_namespace, meta.feature_category.
• remote_ip, client_id, caller_id (controller/action/worker name).
• For Sidekiq jobs: queue name, job class, args (filtered).

To attach context inside a service:

Gitlab::ApplicationContext.with_context(user: current_user, project: project) do
  # ...
end

Context propagates to child Sidekiq jobs automatically.

Structured logging from your code

include Gitlab::Loggable

log_payload = build_structured_payload(event: 'cleanup_done', count: 10)
Gitlab::AppJsonLogger.info(log_payload)

Avoid Rails.logger.info; use the domain-specific logger.

Where logs go

• GDK: under log/, tail with gdk tail.
• Omnibus: /var/log/gitlab/<service>/.
• Helm chart: stdout of each pod, scraped by the cluster's logging stack.
• GitLab.com: ingested into a centralized log warehouse (queryable via internal Kibana / Elastic Cloud).

Sensitive data

Gitlab::Logging::Filter and the parameter filter list in config/initializers/filter_parameters.rb redact tokens, passwords, and emails from logs. Don't log current_user.encrypted_password — the filter would catch it but it's the wrong thing to log anyway.

Adding a new logger

# lib/gitlab/foo_logger.rb
module Gitlab
  class FooLogger < Gitlab::JsonLogger
    def self.file_name_noext
      'foo'
    end
  end
end

Document it in doc/administration/logs.md.

Correlation IDs

A correlation ID is generated at the edge (Workhorse → Rails). It's propagated through HTTP headers, Sidekiq jobs, gRPC calls (Gitaly), and AI Gateway. To find every log line for a request, search by correlation ID.

Related

• Tracing — same context flows into traces.
• Metrics — same labels flow into metrics.