googlecloudlogentryencodingextension

README

Google Cloud LogEntry encoding extension

Status
Stability	alpha
Distributions	contrib
Issues
Code Owners	@alexvanboxel

This extension can be used fo unmarshaling a Cloud Logging LogEntry message type.

The following configuration options are supported:

• handle_json_payload_as (Optional): This controls how the json payload of the LogEntry is parsed into the body. The default json parses it as standard JSON, while text will the put the payload as a single string.
• handle_proto_payload_as (Optional): This controls how the json payload of the LogEntry is parsed into the body. The default json parses it as standard JSON, while proto will use the well known protobuf types used in a LogEntry providing a better type handling, but sacrificing stability. Using text will the put the payload as a single string.

The encoding is mainly used in conjunction with the googlecloudpubsubreceiver. The receiver can be used to bring Cloud Logging messages into an OpenTelemetry pipeline. You'll first need to set up a logging sink with a Pub/Sub topic as its destination. This encoder can be configure to parse the LogEntry. An example config could look like this:

extensions:
  googlecloudlogentry_encoding:
    handle_json_payload_as: "json"
    handle_proto_payload_as: "json"

receivers:
  googlecloudpubsub:
    project: otel-project
    subscription: projects/otel-project/subscriptions/otlp-logs
    encoding: googlecloudlogentry_encoding

Google Cloud logging uses the LogEntry to carry log information. In this section, the mapping of the fields to OpenTelemetry fields and attributes are documented.

Semantic Mapping

Some of the attributes can be moved to OpenTelemetry Semantic Conventions. Note, however, that all the attributes are considered experimental and are subject to change.

Field	Type	Description	Maps to Unified Model Field
insert_id	boolean	A unique identifier for the log entry.	Attributes["log.record.uid"]

Attribute and Field mapping

The rest of the JSON body is either mapped to attributes with a gcp prefix or directly mapped to the LogRecord.

Field	Type	Description	Maps to Unified Model Field
timestamp	string	The time the event described by the log entry occurred.	Timestamp
receiveTimestamp	string	The time the log entry was received.	ObservedTimestamp
logName	string	The URL-encoded log ID suffix of the log_name field identifies which log stream this entry belongs to.	Attributes["gcp.log_name"] (string)
jsonPayload	google.protobuf.Struct	The log entry payload, represented as a structure that is expressed as a JSON object.	Body (KVList)
protoPayload	google.protobuf.Any	The log entry payload, represented as a protocol buffer.	Body (KVList, key from JSON representation)
textPayload	string	The log entry payload, represented as a Unicode string (UTF-8).	Body (string)
trace	string	The trace associated with the log entry, if any.	TraceId
spanId	string	The span ID within the trace associated with the log entry.	SpanId
traceSampled	boolean	The sampling decision of the trace associated with the log entry.	TraceFlags.SAMPLED
labels	map<string,string>	A set of user-defined (key, value) data that provides additional information about the log entry.	Attributes["gcp.*"]
resource	MonitoredResource	The monitored resource that produced this log entry.	Resource["gcp.*"]
httpRequest	HttpRequest	The HTTP request associated with the log entry, if any.	Attributes["gcp.http_request"] (KVList)
operation	LogEntryOperation	Information about a operation associated with the log entry.	Attributes["gcp.operation"] (KVList)
sourceLocation	LogEntrySourceLocation	Source code location information associated with the log entry.	Attributes["gcp.source_location"] (KVList)
split	LogSplit	Information indicating this LogEntry is part of a sequence of multiple log entries split from a single LogEntry.	Attributes["gcp.log_split"] (KVList)

Severity Mapping

The severity is mapping from Google Cloud Log Severity to the OpenTelemetry Severity Number.

CloudLog	Severity Number	CloudLog Description
DEFAULT(0)	UNSPECIFIED(0)	The log entry has no assigned severity level.
DEBUG(100)	DEBUG(5)	Debug or trace information.
INFO(200)	INFO(9)	Routine information, such as ongoing status or performance.
NOTICE(300)	INFO2(10)	Normal but significant events, such as start up, shut down, or a configuration change.
WARNING(400)	WARN(13)	Warning events might cause problems.
ERROR(500)	ERROR(17)	Error events are likely to cause problems.
CRITICAL(600)	FATAL(21)	Critical events cause more severe problems or outages.
ALERT(700)	FATAL2(22)	A person must take an action immediately.
EMERGENCY(800)	FATAL4(24)	One or more systems are unusable.

Documentation

Index

• func NewFactory() extension.Factory
• type Config
  • func (config *Config) Validate() error
• type HandleAs

Functions

func NewFactory

func NewFactory() extension.Factory

Types

type Config

type Config struct {
	// Controls how the json payload of the [LogEntry]  is parsed into the body.
	HandleJSONPayloadAs HandleAs `mapstructure:"handle_json_payload_as"`
	// Controls how the proto payload of the [LogEntry]  is parsed into the body.
	HandleProtoPayloadAs HandleAs `mapstructure:"handle_proto_payload_as"`
	// contains filtered or unexported fields
}

func (*Config) Validate

func (config *Config) Validate() error

type HandleAs

type HandleAs string

const (
	HandleAsProtobuf HandleAs = "protobuf"
	HandleAsJSON     HandleAs = "json"
	HandleAsText     HandleAs = "text"
)