New component: Sumo Logic extension (open-telemetry#29603)

**Description:**

Adds new component (sumologicextension). This is only factory and
configuration PR

**Link to tracking Issue:** open-telemetry#29601 

**Testing:** N/A

**Documentation:**

- readme
- metadata.yaml

---------

Signed-off-by: Dominik Rosiek <[email protected]>
Co-authored-by: Antoine Toulme <[email protected]>
Co-authored-by: Andrzej Stencel <[email protected]>

.chloggen/drosiek-sumologicextension.yaml

@@ -0,0 +1,27 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: new_component
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: sumologicextension
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: add configuration and readme
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [29601]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [user]

.github/CODEOWNERS

@@ -112,6 +112,7 @@ extension/solarwindsapmsettingsextension/ @open-telemetry/collect
 extension/storage/ @open-telemetry/collector-contrib-approvers @dmitryax @atoulme @djaglowski
 extension/storage/dbstorage/ @open-telemetry/collector-contrib-approvers @dmitryax @atoulme
 extension/storage/filestorage/ @open-telemetry/collector-contrib-approvers @djaglowski
+extension/sumologicextension/ @open-telemetry/collector-contrib-approvers @astencel-sumo @sumo-drosiek @swiatekm-sumo
 
 internal/aws/ @open-telemetry/collector-contrib-approvers @Aneurysm9 @mxiamxia
 internal/collectd/ @open-telemetry/collector-contrib-approvers @atoulme

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -111,6 +111,7 @@ body:
  - extension/storage
  - extension/storage/dbstorage
  - extension/storage/filestorage
+ - extension/sumologic
  - internal/aws
  - internal/collectd
  - internal/core

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -105,6 +105,7 @@ body:
  - extension/storage
  - extension/storage/dbstorage
  - extension/storage/filestorage
+ - extension/sumologic
  - internal/aws
  - internal/collectd
  - internal/core

.github/ISSUE_TEMPLATE/other.yaml

@@ -105,6 +105,7 @@ body:
  - extension/storage
  - extension/storage/dbstorage
  - extension/storage/filestorage
+ - extension/sumologic
  - internal/aws
  - internal/collectd
  - internal/core

extension/sumologicextension/.gitignore

@@ -0,0 +1 @@
+coverage.*

extension/sumologicextension/Makefile

@@ -0,0 +1 @@
+include ../../Makefile.Common

extension/sumologicextension/README.md

@@ -0,0 +1,163 @@
+# Sumo Logic Extension
+<!-- status autogenerated section -->
+| Status | |
+| ------------- |-----------|
+| Stability | [development] |
+| Distributions | [sumo] |
+| Issues | [![Open issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector-contrib?query=is%3Aissue%20is%3Aopen%20label%3Aextension%2Fsumologic%20&label=open&color=orange&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues?q=is%3Aopen+is%3Aissue+label%3Aextension%2Fsumologic) [![Closed issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector-contrib?query=is%3Aissue%20is%3Aclosed%20label%3Aextension%2Fsumologic%20&label=closed&color=blue&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues?q=is%3Aclosed+is%3Aissue+label%3Aextension%2Fsumologic) |
+| [Code Owners](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/CONTRIBUTING.md#becoming-a-code-owner) | [@astencel-sumo](https://www.github.com/astencel-sumo), [@sumo-drosiek](https://www.github.com/sumo-drosiek), [@swiatekm-sumo](https://www.github.com/swiatekm-sumo) |
+
+[development]: https://github.com/open-telemetry/opentelemetry-collector#development
+[sumo]: https://github.com/SumoLogic/sumologic-otel-collector
+<!-- end autogenerated section -->
+
+This extension is to be used in conjunction with
+[`sumologicexporter`][sumologicexporter] in order to export telemetry data to
+[Sumo Logic][sumologic].
+
+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
+
+[sumologicexporter]: ../../exporter/sumologicexporter/
+[sumologic]: https://www.sumologic.com/
+
+## Implementation
+
+It implements [`HTTPClientAuthenticator`][httpclientauthenticator]
+and can be used as an authenticator for the
+[`configauth.Authentication`][configauth_authentication] option for HTTP clients.
+
+[httpclientauthenticator]: https://github.com/open-telemetry/opentelemetry-collector/blob/2e84285efc665798d76773b9901727e8836e9d8f/config/configauth/clientauth.go#L34-L39
+[configauth_authentication]: https://github.com/open-telemetry/opentelemetry-collector/blob/3f5c7180c51ed67a6f54158ede5e523822e9659e/config/configauth/configauth.go#L29-L33
+
+## Configuration
+
+- `installation_token`: (required) collector installation token for the Sumo Logic service, see
+ [help][credentials_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][clobber] 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][fields_help]
+- `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](#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][clobber] 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](https://pkg.go.dev/github.com/cenkalti/backoff/v4#ExponentialBackOff) 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`)
+
+[credentials_help]: https://help.sumologic.com/docs/manage/security/installation-tokens
+[fields_help]: https://help.sumologic.com/docs/manage/fields
+[clobber]: https://help.sumologic.com/docs/send-data/installed-collectors/collector-installation-reference/force-collectors-name-clobber/
+
+## Example Config
+
+```yaml
+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:
+
+```go
+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.

extension/sumologicextension/config.go

@@ -0,0 +1,95 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package sumologicextension // import "github.com/open-telemetry/opentelemetry-collector-contrib/extension/sumologicextension"
+
+import (
+ "time"
+
+ "go.opentelemetry.io/collector/config/confighttp"
+ "go.opentelemetry.io/collector/config/configopaque"
+)
+
+// Config has the configuration for the sumologic extension.
+type Config struct {
+ // squash ensures fields are correctly decoded in embedded struct.
+ confighttp.HTTPClientSettings `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"`
+}
+
+type accessCredentials struct {
+ InstallationToken configopaque.String `mapstructure:"installation_token"`
+}
+
+// backOff configuration. See following link for details:
+// https://pkg.go.dev/github.com/cenkalti/backoff/v4#ExponentialBackOff
+type backOffConfig struct {
+ InitialInterval time.Duration `mapstructure:"initial_interval"`
+ MaxInterval time.Duration `mapstructure:"max_interval"`
+ MaxElapsedTime time.Duration `mapstructure:"max_elapsed_time"`
+}

extension/sumologicextension/extension.go

@@ -0,0 +1,33 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package sumologicextension // import "github.com/open-telemetry/opentelemetry-collector-contrib/extension/sumologicextension"
+
+import (
+ "context"
+ "time"
+
+ "go.opentelemetry.io/collector/component"
+ "go.uber.org/zap"
+)
+
+type SumologicExtension struct {
+}
+
+const DefaultHeartbeatInterval = 15 * time.Second
+
+func init() {
+}
+
+func newSumologicExtension(_ *Config, _ *zap.Logger, _ component.ID, _ string) (*SumologicExtension, error) {
+ return &SumologicExtension{}, nil
+}
+
+func (se *SumologicExtension) Start(_ context.Context, _ component.Host) error {
+ return nil
+}
+
+// Shutdown is invoked during service shutdown.
+func (se *SumologicExtension) Shutdown(_ context.Context) error {
+ return nil
+}