New component: Oracle Observability Exporter [exporter/oracleobservabilityexporter]

[naga-barri]

The purpose and use-cases of the new component

The Oracle Observability Exporter is a component of the OpenTelemetry Collector that enables the export of logs to OCI Logging Analytics.

The exporter plugin uses OCI authentication and authorization (AuthN/AuthZ) to securely export data from the customer environment to the OCI Logging Analytics service.

Example configuration for the component

The following settings are required:

• namespace (no default): The OCI tenancy namespace to which the collected log data will be uploaded.
• log_group_id (no default): The log group OCID to which the log data will be mapped. This is mainly used for AuthZ purpose.
• auth_type (default: config_file): The authentication type to use. Supported values are:
  • config_file: Use OCI configuration file for authentication.
  • instance_principal: Use OCI instance principal for authentication. Recommended when the collector is deployed inside OCI environment.
• oci_config_file_path: Path to the OCI configuration file. If auth_type is config_file and this is not provided, the exporter will search for the configuration in the default location ($HOME/.oci/config or the location specified by the OCI_CONFIG_FILE environment variable).
• config_profile (default: DEFAULT): The profile to be used in the OCI configuration file, if auth_type is config_file.
• private_key_passphrase (no default): Passphrase for the private key used in the config file, if the key is password-protected. Only applicable when auth_type is config_file.
• oci_config (no default): An alternative way to provide the content of the OCI Config file, if auth_type is config_file. The following fields are required:
  • fingerprint (no default): The fingerprint of the OCI user.
  • private_key (no default): The private key of the OCI user.
  • tenancy (no default): The OCI tenancy OCID.
  • region (no default): The OCI region.
  • user (no default): The OCI user OCID.

NOTE: If both oci_config_file_path and oci_config are provided, the exporter will use oci_config over oci_config_file_path.

Example:

exporters:
  oracleobservability:
    namespace: "my_namespace"
    log_group_id: "ocid1.loggroup.oc1..example"
    auth_type: "config_file"
    oci_config_file_path: "/path/to/oci/config"
    config_profile: "DEFAULT"

Optional Settings
The following settings can be optionally configured:

• timeout (default: 0s): The maximum duration before a request times out.

• sending_queue:

  • enabled (default: true): If true, logs will be buffered in a queue before being sent. If false, logs are sent immediately to the consumer without buffering.
  • num_consumers (default: 10): The number of consumers processing logs from the queue.
  • block_on_overflow (default = false): If true, blocks the request until space is available in the queue. If set to false, the exporter immediately returns an error if the queue is full.
  • sizer (default = requests): How the queue and batching is measured. Available options:
    • requests: number of incoming batches of metrics, logs, traces (the most performant option);
    • items: number of the smallest parts of each signal (spans, metric data points, log records);
    • bytes: the size of serialized data in bytes (the least performant option).
  • queue_size (default: 1000): The maximum number of logs that can be buffered before older logs are dropped.
  • batch (default: disabled): It only supports if sizer is set as items or bytes.
    • flush_timeout: time after which a batch will be sent regardless of its size. Must be a non-zero value
    • min_size: the minimum size of a batch.
    • max_size: the maximum size of a batch, enables batch splitting. The maximum size of a batch should be greater than or equal to the minimum size of a batch.
  • storage (default = 'file_storage'): When set, enables persistence and uses the component specified as a storage extension for the persistent queue. There is no in-memory queue when set. The file_storage extension must be explicitly configured in config.yaml under extensions: and included in service::extensions for it to take effect. More information regarding filestorage extension can be found at File Storage Extension

• retry_on_failure:

  • enabled (default: true): If true, failed requests will be retried.
  • initial_interval (default: 5s): The initial time to wait before retrying a failed request.
  • max_interval (default: 30s): The maximum time to wait between retries.
  • max_elapsed_time (default: 0): The maximum time allowed for all retries. If set to 0 (default value), the failed requests will be infinitely retried.
  • multiplier (default = 1.5): Factor by which the retry interval is multiplied on each attempt; ignored if enabled is false
  • randomization_factor (default = 0.5): RandomizationFactor is a random factor used to calculate next backoffs.

Example:

exporters:
  oracleobservability:
    namespace: "my_namespace"
    log_group_id: "ocid1.loggroup.oc1..example"
    auth_type: "config_file"
    oci_config_file_path: "/path/to/oci/config"
    config_profile: "DEFAULT"
    timeout: 10s
    sending_queue:
      enabled: true
      queue_size: 5000
      num_consumers: 12
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s

Telemetry data types supported

logs

Code Owner(s)

No response

Sponsor (optional)

No response

Additional context

No response

[atoulme]

Please note you need to be OpenTelemetry members to be a codeowner. Please see CONTRIBUTING.md.

[marcalff]

@naga-barri
cc @atoulme

I can be @naga-barri sponsor, to join the CNCF as a member.

Please see the process here:

https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md

I am a maintainer of opentelemetry-cpp (and disclosure: an Oracle employee).