webhookeventreceiver

README

Webhook Event Receiver

The Webhook Event Receiver is a push based event collector component meant to act as a generally available receiver for any webhook style data source. It is designed to work alongside other pipeline components like the transform processor to allow the ingestion of generic events as logs into the opentelemetry collector.

Status
Stability	beta: logs
Distributions	contrib
Issues
Code coverage
Code Owners	@atoulme, @shalper2

Configuration

Note: This receiver was renamed from webhookevent to webhook_event to match the snake_case naming convention. The deprecated component type webhookevent is still accepted as an alias and will log a deprecation warning.

The following settings are required:

• endpoint (no default): The endpoint where you may point your webhook to emit events to

The following settings are optional:

• path (default: '/events'): Path where the receiver instance will accept events
• health_path (default: '/health_check'): Path available for checking receiver status
• read_timeout (default: '500ms'): Maximum wait time while attempting to read a received event
• write_timeout (default: '500ms'): Maximum wait time while attempting to write a response
• required_header (optional):
  • key (required if required_header config option is set): Represents the key portion of the required header.
  • value (required if required_header config option is set): Represents the value portion of the required header.
• split_logs_at_newline (default: false): If true, the receiver will create a separate log record for each line in the request body.
• split_logs_at_json_boundary (default: false): If true, the receiver will parse the request body to JSON and send each object as a log. Splitting on new line overrides json boundary so only enable one at a time.
• convert_headers_to_attributes (optional): add all request headers (excluding required_header if also set) log attributes
• header_attribute_regex (optional): add headers matching supplied regex as log attributes. Header attributes will be prefixed with header.
• max_request_body_size (default comes from confighttp module): Maximum size in bytes for request body. Requests exceeding this limit will be rejected with an error.

Split logs at newline example

If the setting is unconfigured or set to false, the receiver will create a single log record with the entire request body as the "body" of that record.

If the webhook body looks like the following, use split_logs_at_newline: false:

{
"name": "francis",
"city": "newyork"
}
a fifth line

A single log record will be created with the multi-line JSON object as the "body" of that record, even the "fifth line" outside the JSON object will be included.

If the body looks like the following, use split_logs_at_newline: true:

{ "name": "francis", "city": "newyork" }
{ "name": "john", "city": "paris" }
a third line

Three log records will be created from this example. The first two are JSON body objects and the third is just the string "a third line".

This receiver does not attempt to marshal the body into a structured format as it is received so it cannot make a more intelligent determination about where the split records.

Split logs at JSON boundary example

If you don't have clear new-line splits between objects, the receiver can use the JSON parser to handle separating the objects. split_logs_at_json_boundary: true

{ "name": "francis", "city": "newyork", "multiple lines?": "you 
know it!"}
{ "name": "john", "city": "paris" }{ "name": "tim", "city": "london" }

This settings works when JSON objects have newlines in the middle of a string or multiple objects on a line.

Configuration Example

receivers:
    webhook_event:
        endpoint: localhost:8088
        read_timeout: "500ms"
        path: "eventsource/receiver"
        health_path: "eventreceiver/healthcheck"
        required_header:
            key: "required-header-key"
            value: "required-header-value"
        split_logs_at_newline: false
        max_request_body_size: 1000000000

The full list of settings exposed for this receiver are documented in config.go with a detailed sample configuration in testdata/config.yaml

Documentation

Index

• func NewFactory() receiver.Factory
• type Config
  • func (cfg *Config) ShouldSplitLogsAtJSONBoundary() bool
  • func (cfg *Config) Validate() error
• type RequiredHeader

Functions

func NewFactory

func NewFactory() receiver.Factory

NewFactory creates a factory for Generic Webhook Receiver.

Types

type Config

type Config struct {
	confighttp.ServerConfig    `mapstructure:",squash"` // squash ensures fields are correctly decoded in embedded struct
	ReadTimeout                string                   `mapstructure:"read_timeout"`                  // wait time for reading request headers in ms. Default is 500ms.
	WriteTimeout               string                   `mapstructure:"write_timeout"`                 // wait time for writing request response in ms. Default is 500ms.
	Path                       string                   `mapstructure:"path"`                          // path for data collection. Default is /events
	HealthPath                 string                   `mapstructure:"health_path"`                   // path for health check api. Default is /health_check
	RequiredHeader             RequiredHeader           `mapstructure:"required_header"`               // optional setting to set a required header for all requests to have
	SplitLogsAtNewLine         bool                     `mapstructure:"split_logs_at_newline"`         // optional setting to split logs into multiple log records
	SplitLogsAtJSONBoundary    bool                     `mapstructure:"split_logs_at_json_boundary"`   // optional setting to split logs at JSON object boundaries
	ConvertHeadersToAttributes bool                     `mapstructure:"convert_headers_to_attributes"` // optional to convert all headers to attributes
	HeaderAttributeRegex       string                   `mapstructure:"header_attribute_regex"`        // optional to convert headers matching a regex to log attributes
}

Config defines configuration for the Generic Webhook receiver.

func (*Config) ShouldSplitLogsAtJSONBoundary

func (cfg *Config) ShouldSplitLogsAtJSONBoundary() bool

func (*Config) Validate

func (cfg *Config) Validate() error

type RequiredHeader

type RequiredHeader struct {
	Key   string `mapstructure:"key"`
	Value string `mapstructure:"value"`
}