sumologicextension

README

Sumo Logic Extension

Status
Stability	alpha
Distributions	[]
Issues
Code Owners	@rnishtala-sumo, @chan-tim-sumo
Emeritus	@aboguszewski-sumo, @kasia-kujawa, @mat-rumian, @sumo-drosiek

This extension is to be used in conjunction with sumologicexporter in order to export telemetry data to Sumo Logic.

It manages:

• authentication (passing the provided credentials to sumologicexporter when configured as extension in the same service)
• registration (storing the registration info locally after successful registration for later use)
• heartbeats

Implementation

It implements HTTPClientAuthenticator and can be used as an authenticator for the configauth.Authentication option for HTTP clients.

Configuration

• installation_token: (required) collector installation token for the Sumo Logic service, see help for more details

• collector_name: name that will be used for registration; by default the hostname is used. In the event of a conflict, a timestamp will be appended to the name. See here for more information.

• collector_description: collector description that will be used for registration

• collector_category: collector category that will be used for registration

• collector_fields: a map of key value pairs that will be used as collector fields that will be used for registration. For more information on this subject please visit this help document

• discover_collector_tags: defines whether to auto-discover collector metadata tags (for local services, e.g. mysql) (default: true)

  NOTE: collector metadata tag auto-discovery is an alpha feature.

• api_base_url: base API URL that will be used for creating API requests, see API URLs details (default: https://open-collectors.sumologic.com)

• heartbeat_interval: interval that will be used for sending heartbeats (default: 15s)

• collector_credentials_directory: directory where state files with registration info will be stored after successful collector registration (default: $HOME/.sumologic-otel-collector)

• clobber: defines whether to delete any existing collector with the same name. See here for more information.

• force_registration: defines whether to force registration every time the collector starts. This will cause the collector to not look at the locally stored credentials and to always reach out to API to register itself. (default: false)

  NOTE: if clobber is unset (default) then setting this to true will create a new collector (with new unique name) on Sumo UI on every collector start and create a new one upon registration.

• ephemeral: defines whether the collector will be deleted after 12 hours of inactivity (default: false)

• time_zone: defines the time zone of the collector, for example "America/Los_Angeles". For a list of all possible values, refer to the TZ identifier column in https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List

• backoff: defines backoff mechanism for retry in case of failed registration. Exponential algorithm is being used.

  • initial_interval - initial interval of backoff (default: 500ms)
  • max_interval - maximum interval of backoff (default: 1m)
  • max_elapsed_time - time after which registration fails definitely (default: 15m)
  • sticky_session_enabled - enable sticky session support (default: false)

Example Config

extensions:
  sumologic:
    installation_token: <token>
    collector_name: my_collector
    time_zone: Europe/Warsaw

receivers:
  hostmetrics:
    collection_interval: 30s
    scrapers:
      load:

processors:

exporters:
  sumologic:
    auth:
      authenticator: sumologic # Specify the name of the authenticator extension

service:
  extensions: [sumologic]
  pipelines:
    metrics:
      receivers: [hostmetrics]
      processors: []
      exporters: [sumologic]

API URLs

When integrating the extension with different Sumo Logic deployment that the default one (i.e. https://open-collectors.sumologic.com) one needs to specify the base API URL in the configuration (via api_base_url option) in order to specify against which URL the agent will be authenticating against.

Here is a list of valid values for this configuration option:

Deployment	API base URL
default/US1	https://open-collectors.sumologic.com
US2	https://open-collectors.us2.sumologic.com
AU	https://open-collectors.au.sumologic.com
DE	https://open-collectors.de.sumologic.com
EU	https://open-collectors.eu.sumologic.com
JP	https://open-collectors.jp.sumologic.com
CA	https://open-collectors.ca.sumologic.com
IN	https://open-collectors.in.sumologic.com

Storing credentials

When collector is starting for the first time, Sumo Logic extension is using the installation_token to register the collector with API. Upon registration, the extension gets collector credentials which are used to authenticate the collector when sending request to API (heartbeats, sending data etc).

Credentials are stored on local filesystem to be reused when collector gets restarted (to prevent re-registration). The path that's used to store the credentials files is configured via collector_credentials_directory which is by default set to $HOME/.sumologic-otel-collector.

Name of that file that contains the credentials is created in the following manner:

filename := hash(collector_name, installation_token, api_base_url)

This mechanism allows to keep the state of the collector (whether it is registered or not). When collector is restarting it checks if the state file exists in collector_credentials_directory.

If one would like to register another collector on the same machine then collector_name configuration property has to be specified in order to register the collector under that specific name which will be used to create a separate state file.

Running the collector as systemd service

Systemd services are often run as users without a home directory, so if the collector is run as such service, the credentials might not be stored properly. One should either make sure that the home directory exists for the user or change the store location to another directory.

Documentation

Index

• Constants
• func NewFactory() extension.Factory
• type Config
• type ErrorAPI
  • func (e ErrorAPI) Error() string
• type SumologicExtension
  • func (se *SumologicExtension) BaseURL() string
  • func (se *SumologicExtension) CollectorID() string
  • func (se *SumologicExtension) ComponentID() component.ID
  • func (se *SumologicExtension) CreateCredentialsHeader() (http.Header, error)
  • func (se *SumologicExtension) PerRPCCredentials() (grpccredentials.PerRPCCredentials, error)
  • func (se *SumologicExtension) RoundTripper(base http.RoundTripper) (http.RoundTripper, error)
  • func (se *SumologicExtension) SetBaseURL(baseURL string)
  • func (se *SumologicExtension) SetStickySessionCookie(stickySessionCookie string)
  • func (se *SumologicExtension) Shutdown(ctx context.Context) error
  • func (se *SumologicExtension) Start(ctx context.Context, host component.Host) error
  • func (se *SumologicExtension) StickySessionCookie() string
  • func (se *SumologicExtension) WatchCredentialKey(ctx context.Context, old string) string

Constants

const (
	// The value of extension "type" in configuration.
	DefaultAPIBaseURL = "https://open-collectors.sumologic.com"
)

const (
	DefaultHeartbeatInterval = 15 * time.Second
)

Functions

func NewFactory

func NewFactory() extension.Factory

NewFactory creates a factory for Sumo Logic extension.

Types

type Config

type Config struct {
	// squash ensures fields are correctly decoded in embedded struct.
	confighttp.ClientConfig `mapstructure:",squash"`

	// Credentials contains Installation Token for Sumo Logic service.
	// Please refer to https://help.sumologic.com/docs/manage/security/installation-tokens
	// for detailed instructions how to obtain the token.
	Credentials accessCredentials `mapstructure:",squash"`

	// CollectorName is the name under which collector will be registered.
	// Please note that registering a collector under a name which is already
	// used is not allowed.
	CollectorName string `mapstructure:"collector_name"`
	// CollectorEnvironment is the environment which will be used when updating
	// the collector metadata.
	CollectorEnvironment string `mapstructure:"collector_environment"`
	// CollectorDescription is the description which will be used when the
	// collector is being registered.
	CollectorDescription string `mapstructure:"collector_description"`
	// CollectorCategory is the collector category which will be used when the
	// collector is being registered.
	CollectorCategory string `mapstructure:"collector_category"`
	// CollectorFields defines the collector fields.
	// For more information on this subject visit:
	// https://help.sumologic.com/docs/manage/fields
	CollectorFields map[string]any `mapstructure:"collector_fields"`

	// DiscoverCollectorTags enables collector metadata tag auto-discovery.
	DiscoverCollectorTags bool `mapstructure:"discover_collector_tags"`

	APIBaseURL string `mapstructure:"api_base_url"`

	HeartBeatInterval time.Duration `mapstructure:"heartbeat_interval"`

	// CollectorCredentialsDirectory is the directory where state files
	// with collector credentials will be stored after successful collector
	// registration. Default value is $HOME/.sumologic-otel-collector
	CollectorCredentialsDirectory string `mapstructure:"collector_credentials_directory"`

	// Clobber defines whether to delete any existing collector with the same
	// name and create a new one upon registration.
	// By default this is false.
	Clobber bool `mapstructure:"clobber"`

	// ForceRegistration defines whether to force registration every time the
	// collector starts.
	// This will cause the collector to not look at the locally stored credentials
	// and to always reach out to API to register itself.
	//
	// NOTE: if clobber is unset (default) then setting this to true will create
	// a new collector on Sumo UI on every collector start.
	//
	// By default this is false.
	ForceRegistration bool `mapstructure:"force_registration"`

	// Ephemeral defines whether the collector will be deleted after 12 hours
	// of inactivity.
	// By default this is false.
	Ephemeral bool `mapstructure:"ephemeral"`

	// TimeZone defines the time zone of the Collector.
	// For a list of possible values, refer to the "TZ" column in
	// https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List.
	TimeZone string `mapstructure:"time_zone"`

	// BackOff defines configuration of collector registration backoff algorithm
	// Exponential algorithm is being used.
	// Please see following link for details: https://github.com/cenkalti/backoff
	BackOff backOffConfig `mapstructure:"backoff"`

	// StickySessionEnabled defines if sticky session support is enable.
	// By default this is false.
	StickySessionEnabled bool `mapstructure:"sticky_session_enabled"`
}

Config has the configuration for the sumologic extension.

type ErrorAPI

type ErrorAPI struct {
	// contains filtered or unexported fields
}

func (ErrorAPI) Error

func (e ErrorAPI) Error() string

type SumologicExtension

type SumologicExtension struct {
	// contains filtered or unexported fields
}

func (*SumologicExtension) BaseURL

func (se *SumologicExtension) BaseURL() string

func (*SumologicExtension) CollectorID

func (se *SumologicExtension) CollectorID() string

func (*SumologicExtension) ComponentID

func (se *SumologicExtension) ComponentID() component.ID

func (*SumologicExtension) CreateCredentialsHeader

func (se *SumologicExtension) CreateCredentialsHeader() (http.Header, error)

CreateCredentialsHeader produces an HTTP header containing authentication credentials. This function is for components that do not make use of the RoundTripper or have an HTTP request to build upon.

func (*SumologicExtension) PerRPCCredentials

func (se *SumologicExtension) PerRPCCredentials() (grpccredentials.PerRPCCredentials, error)

func (*SumologicExtension) RoundTripper

func (se *SumologicExtension) RoundTripper(base http.RoundTripper) (http.RoundTripper, error)

Implement 1 in order for this extension to be used as custom exporter authenticator.

func (*SumologicExtension) SetBaseURL

func (se *SumologicExtension) SetBaseURL(baseURL string)

func (*SumologicExtension) SetStickySessionCookie

func (se *SumologicExtension) SetStickySessionCookie(stickySessionCookie string)

func (*SumologicExtension) Shutdown

func (se *SumologicExtension) Shutdown(ctx context.Context) error

Shutdown is invoked during service shutdown.

func (*SumologicExtension) Start

func (se *SumologicExtension) Start(ctx context.Context, host component.Host) error

func (*SumologicExtension) StickySessionCookie

func (se *SumologicExtension) StickySessionCookie() string

func (*SumologicExtension) WatchCredentialKey

func (se *SumologicExtension) WatchCredentialKey(ctx context.Context, old string) string

WatchCredentialKey watches for credential key updates. It makes use of a channel close (done by injectCredentials) and string comparison with a known/previous credential key (old). This function allows components to be proactive when dealing with changes to authentication.