Class: SemanticLogger::Formatters::Ecs

Inherits:
Raw
  • Object
show all
Defined in:
lib/semantic_logger/formatters/ecs.rb

Overview

Formatter conforming to the Elastic Common Schema (ECS).

Emits log events using the nested field names defined by ECS so that they integrate cleanly with Filebeat and the Elastic stack (Elasticsearch, Kibana) without requiring an ingest pipeline to rename fields.

Usage:

SemanticLogger.add_appender(io: $stdout, formatter: :ecs)

# Route the payload, metric, and other SemanticLogger-specific data into
# a custom top-level namespace (default "semantic_logger"):
SemanticLogger.add_appender(io: $stdout, formatter: {ecs: {namespace: "my_app"}})

# Or merge the payload directly into ECS `labels` instead of a namespace:
SemanticLogger.add_appender(io: $stdout, formatter: {ecs: {namespace: nil}})

Field mapping (SemanticLogger -> ECS 8.x)

time -> @timestamp (ISO-8601) level -> log.level name -> log.logger file_name / line -> log.origin.file.name / log.origin.file.line message -> message thread_name -> process.thread.name pid -> process.pid host -> host.hostname application -> service.name environment -> service.environment exception -> error.type / error.message / error.stack_trace duration -> event.duration (nanoseconds, as required by ECS) tags -> tags (ECS top-level array) named_tags -> labels.* (scalar key/value pairs) payload -> .* (or labels.* when namespace is nil) metric/metric_amount -> .metric / .metric_amount

Reference

Constant Summary collapse

ECS_VERSION =

ECS version this formatter targets.

"8.11.0".freeze

Instance Attribute Summary collapse

Attributes inherited from Raw

#hash, #time_key

Attributes inherited from Base

#filter, #instance_named_tags, #instance_tags, #name

Instance Method Summary collapse

Methods inherited from Raw

#application, #duration, #environment, #exception, #file_name_and_line, #host, #level, #message, #metric, #name, #named_tags, #payload, #pid, #tags, #thread_name, #time

Methods inherited from Base

#backtrace, #fast_tag, #level, #level=, #log, #measure, #named_tags, #pop_tags, #push_tags, #should_log?, #silence, #tagged, #tags, #with_level

Constructor Details

#initialize(namespace: "semantic_logger", time_format: :iso_8601, time_key: :timestamp, **args) ⇒ Ecs

Returns a new instance of Ecs.



53
54
55
56
57
 
# File 'lib/semantic_logger/formatters/ecs.rb', line 53

def initialize(namespace: "semantic_logger", time_format: :iso_8601, time_key: :timestamp, **args)
  @namespace = namespace&.to_sym

  super(time_format: time_format, time_key: time_key, **args)
end

Instance Attribute Details

#namespace ⇒ Object (readonly)

namespace: [String|Symbol|nil] Top-level field set used to hold SemanticLogger-specific data that has no native ECS home (payload, metric, metric_amount). A proper-noun namespace is guaranteed never to collide with a current or future ECS field. Set to nil to merge the payload into ECS labels instead. Default: "semantic_logger"



51
52
53
 
# File 'lib/semantic_logger/formatters/ecs.rb', line 51

def namespace
  @namespace
end

Instance Method Details

#batch(logs, logger) ⇒ Object

Returns a batch of log events as a single JSON array.



66
67
68
 
# File 'lib/semantic_logger/formatters/ecs.rb', line 66

def batch(logs, logger)
  "[#{logs.map { |log| call(log, logger) }.join(',')}]"
end

#call(log, logger) ⇒ Object

Returns the log event as a single line of ECS-formatted JSON, so it can be written to stdout / a file and shipped by Filebeat or Elastic Agent.



61
62
63
 
# File 'lib/semantic_logger/formatters/ecs.rb', line 61

def call(log, logger)
  Utils.to_json(ecs_hash(super))
end