chronicleexporter

README

Chronicle Exporter

Currently only v2 of the ingestion API is supported

This exporter facilitates the sending of logs to Chronicle, which is a security analytics platform provided by Google. It is designed to integrate with OpenTelemetry collectors to export telemetry data such as logs to a Chronicle account.

Minimum Collector Versions

• Introduced: v1.39.0

Supported Pipelines

• Logs

How It Works

1. The exporter uses the configured credentials to authenticate with the Google Cloud services.
2. It marshals logs into the format expected by Chronicle.
3. It sends the logs to the appropriate Chronicle endpoint.

Configuration

The exporter can be configured using the following fields:

Field	Type	Default	Required	Description
endpoint	string	malachiteingestion-pa.googleapis.com	false	The Endpoint for sending to chronicle.
creds_file_path	string		true	The file path to the Google credentials JSON file.
creds	string		true	The Google credentials JSON.
log_type	string		false	The type of log that will be sent.
raw_log_field	string		false	The field name for raw logs.
customer_id	string		false	The customer ID used for sending logs.
override_log_type	bool	true	false	Whether or not to override the log_type in the config with attributes["log_type"]
namespace	string		false	User-configured environment namespace to identify the data domain the logs originated from.
compression	string	none	false	The compression type to use when sending logs. valid values are none and gzip
ingestion_labels	map[string]string		false	Key-value pairs of labels to be applied to the logs when sent to chronicle.
collect_agent_metrics	bool	true	false	Enables collecting metrics about the agent's process and log ingestion metrics

Log Type

If the attributes["log_type"] field is present in the log, and maps to a known Chronicle log_type the exporter will use the value of that field as the log type. If the attributes["log_type"] field is not present, the exporter will use the value of the log_type configuration field as the log type.

currently supported log types are:

• windows_event.security
• windows_event.custom
• windows_event.application
• windows_event.system
• sql_server

If the attributes["chronicle_log_type"] field is present in the log, we will use its value in the payload instead of the automatic detection or the log_type in the config.

Namespace and Ingestion Labels

If the attributes["chronicle_namespace"] field is present in the log, we will use its value in the payload instead of the namespace in the config.

If there are nested fields in attributes["chronicle_ingestion_label"], we will use the values in the payload instead of the ingestion_labels in the config.

Credentials

This exporter requires a Google Cloud service account with access to the Chronicle API. The service account must have access to the endpoint specfied in the config. Besides the default endpoint, there are also regional endpoints that can be used here.

For additional information on accessing Chronicle, see the Chronicle documentation.

Example Configuration

Basic Configuration

chronicle:
  creds_file_path: "/path/to/google/creds.json"
  log_type: "ABSOLUTE"
  customer_id: "customer-123"

Basic Configuration with Regional Endpoint

chronicle:
  endpoint: https://malachiteingestion-pa.googleapis.com
  creds_file_path: "/path/to/google/creds.json"
  log_type: "ONEPASSWORD"
  customer_id: "customer-123"

Configuration with Ingestion Labels

chronicle:
  creds_file_path: "/path/to/google/creds.json"
  log_type: ""
  customer_id: "customer-123"
  ingestion_labels:
    env: dev
    zone: USA

Documentation

Overview

Package chronicleexporter exports OpenTelemetry data to Chronicle.

Index

• func NewFactory() exporter.Factory
• type Config
  • func (cfg *Config) Validate() error
• type MockMarshaler
  • func NewMockMarshaler(t interface{ ... }) *MockMarshaler
  • func (_m *MockMarshaler) MarshalRawLogs(ctx context.Context, ld plog.Logs) ([]*api.BatchCreateLogsRequest, error)
  • func (_m *MockMarshaler) MarshalRawLogsForHTTP(ctx context.Context, ld plog.Logs) (map[string]*api.ImportLogsRequest, error)

Functions

func NewFactory

func NewFactory() exporter.Factory

NewFactory creates a new Chronicle exporter factory.

Types

type Config

type Config struct {
	exporterhelper.TimeoutConfig `mapstructure:",squash"` // squash ensures fields are correctly decoded in embedded struct.
	exporterhelper.QueueConfig   `mapstructure:"sending_queue"`
	configretry.BackOffConfig    `mapstructure:"retry_on_failure"`

	// Endpoint is the URL where Chronicle data will be sent.
	Endpoint string `mapstructure:"endpoint"`

	// CredsFilePath is the file path to the Google credentials JSON file.
	CredsFilePath string `mapstructure:"creds_file_path"`

	// Creds are the Google credentials JSON file.
	Creds string `mapstructure:"creds"`

	// LogType is the type of log that will be sent to Chronicle.
	LogType string `mapstructure:"log_type"`

	// OverrideLogType is a flag that determines whether or not to override the `log_type` in the config with `attributes["log_type"]`.
	OverrideLogType bool `mapstructure:"override_log_type"`

	// RawLogField is the field name that will be used to send raw logs to Chronicle.
	RawLogField string `mapstructure:"raw_log_field"`

	// CustomerID is the customer ID that will be used to send logs to Chronicle.
	CustomerID string `mapstructure:"customer_id"`

	// Namespace is the namespace that will be used to send logs to Chronicle.
	Namespace string `mapstructure:"namespace"`

	// Compression is the compression type that will be used to send logs to Chronicle.
	Compression string `mapstructure:"compression"`

	// IngestionLabels are the labels that will be attached to logs when sent to Chronicle.
	IngestionLabels map[string]string `mapstructure:"ingestion_labels"`

	// CollectAgentMetrics is a flag that determines whether or not to collect agent metrics.
	CollectAgentMetrics bool `mapstructure:"collect_agent_metrics"`

	// Protocol is the protocol that will be used to send logs to Chronicle.
	// Either https or grpc.
	Protocol string `mapstructure:"protocol"`

	// Location is the location that will be used when the protocol is https.
	Location string `mapstructure:"location"`

	// Project is the project that will be used when the protocol is https.
	Project string `mapstructure:"project"`

	// Forwarder is the forwarder that will be used when the protocol is https.
	Forwarder string `mapstructure:"forwarder"`
}

Config defines configuration for the Chronicle exporter.

func (*Config) Validate

func (cfg *Config) Validate() error

Validate checks if the configuration is valid.

type MockMarshaler

type MockMarshaler struct {
	mock.Mock
}

MockMarshaler is an autogenerated mock type for the logMarshaler type

func NewMockMarshaler

func NewMockMarshaler(t interface {
	mock.TestingT
	Cleanup(func())
}) *MockMarshaler

NewMockMarshaler creates a new instance of MockMarshaler. It also registers a testing interface on the mock and a cleanup function to assert the mocks expectations. The first argument is typically a *testing.T value.

func (*MockMarshaler) MarshalRawLogs

func (_m *MockMarshaler) MarshalRawLogs(ctx context.Context, ld plog.Logs) ([]*api.BatchCreateLogsRequest, error)

MarshalRawLogs provides a mock function with given fields: ctx, ld

func (*MockMarshaler) MarshalRawLogsForHTTP

func (_m *MockMarshaler) MarshalRawLogsForHTTP(ctx context.Context, ld plog.Logs) (map[string]*api.ImportLogsRequest, error)

MarshalRawLogsForHTTP provides a mock function with given fields: ctx, ld