Skip to content

Latest commit

 

History

History
496 lines (369 loc) · 20.4 KB

upgrading.md

File metadata and controls

496 lines (369 loc) · 20.4 KB
Raw

Upgrading

Upgrading to v0.77.0-sumo-0

Full Prometheus metric name normalization is now disabled by default

Prometheus and otel metric naming conventions aren't entirely compatible. Prometheus metric name normalization is a feature intended to convert metrics between the two conventions. See the upstream documentation for details.

In the 0.76.1 release, the feature flag for this normalization was enabled by default.

The feature primarily affects the prometheus and prometheusremotewrite exporters. However, it also modifies some metrics collected by the prometheus receiver. More specifically, it trims certain suffixes from metric names. Unfortunately, this affects a lot of widely used metrics. For example, the standard container CPU usage metric:

container_cpu_usage_seconds_total -> container_cpu_usage_seconds

This change breaks a lot of content built using existing metric names and prevents the Prometheus receiver from being used as a drop-in replacement for Prometheus. Therefore, we've decided to default to having this flag disabled.

The current behaviour can be re-enabled by passing the --feature-gates=+pkg.translator.prometheus.NormalizeName flag to the collector at startup.

There is an ongoing discussion about making this behaviour configurable at runtime. Please follow this issue if you'd like to learn more.

Upgrading to v0.73.0-sumo-1

The default collector name for sumologic extension is now the host FQDN

In an effort to make defaults consistent between resource detection processor and the Sumo extension, we've changed the default collector name and the host name it reports in its metadata to be the host FQDN instead of the hostname reported by the OS. This makes the value consistent with the value of the host.name attribute resource detection processor sets by default.

This will only affect newly registered collectors. If you have local credentials on your host, the existing collector will be used, but if those credentials are cleared, a new collector will be created with a different name. If you'd like to keep using the old name, set CollectorName explicitly in the extension settings.

Upgrading to v0.66.0-sumo-0

filelog receiver: has been removed from sub-parsers

preserve_to has been removed from sub-parsers (#9331).

Now sub-parsers behaves like preserve_to would be equal to parse_from.

sending_queue: require explicit storage set

persistent_storage_enabled configuration option is no longer available (#5784). It is replaced by storage which takes component name as value:

exporters:
  sumologic:
    sending_queue:
      enabled: true
      storage: file_storage

extensions:
  file_storage:
    directory: .
  sumologic:
    collector_name: sumologic-demo
    installation_token: ${SUMOLOGIC_INSTALLATION_TOKEN}

apache receiver: turn on feature gates for resource attributes

The metrics in this receiver are now being sent with two resource attributes: apache.server.name and apache.server.port. Additionally, apache.server.name replaces server_name metric-level attribute.

Both features are hidden behind feature gates, but because they are important for Sumo Logic apps, they have been enabled by default ahead of the normal deprecation timeline.

To disable the new features, disable the feature gates in otelcol's arguments:

otelcol-sumo --config=file:config.yaml --feature-gates=-receiver.apache.emitServerNameAsResourceAttribute,-receiver.apache.emitPortAsResourceAttribute

More information about the feature gates can be found here. The target release for the removal of feature gates is v0.68.

elasticsearch receiver: turn on more datapoints

The metrics elasticsearch.index.operation.count, elasticsearch.index.operation.time and elasticsearch.cluster.shards emit more data points now.

These features are hidden behind feature gates, but because they are important for Sumo Logic apps, they have been enabled by default ahead of the normal deprecation timeline.

To disable the new features, disable the feature gates in otelcol's arguments:

otelcol-sumo --config=file:config.yaml --feature-gates=-receiver.elasticsearch.emitClusterHealthDetailedShardMetrics,-receiver.elasticsearch.emitAllIndexOperationMetrics

More information about the feature gates can be found here. The target release for the removal of feature gates is v0.71.

Upgrading to v0.57.2-sumo-0

sumologic exporter: drop support for source headers

The following properties of the Sumo Logic exporter are deprecated in v0.57.2-sumo-0:

  • source_category
  • source_host
  • source_name

To upgrade, move these properties from the Sumo Logic exporter configuration to the Source processor.

For example, the following configuration:

exporters:
  sumologic:
    source_category: my-source-category
    source_host: my-source-host
    source_name: my-source-name

should be changed to the following:

processors:
  source:
    source_category: my-source-category
    source_category_prefix: ""
    source_category_replace_dash: "-"
    source_host: my-source-host
    source_name: my-source-name

The reason for the additional source_category_prefix and source_category_replace_dash is that the Source processor has more features and these properties must be set to make it behave like the Sumo Logic exporter.

See the Source processor documentation for more details.

Upgrading to v0.56.0-sumo-0

sumologic exporter: drop support for translating attributes

Translating the attributes is harmless, but the exporters should not modify the data. This functionality has been moved to the sumologicschema processor. Due to that, this functionality is now deprecated in the exporter and will be removed soon.

However, if the attributes are not translated, some Sumo Logic apps might not work correctly. To migrate, add a sumologicschema processor to your pipelines that use the sumologic exporter and disable that functionality in the exporter:

processors:
  # ...
  sumologic_schema:
    translate_attributes: true

exporters:
  sumologic:
    # ...
    translate_attributes: false

# ...

service:
  pipelines:
    logs:
      processors:
        # - ...
        - sumologic_schema

Note: by default, the sumologicschema processor also performs other actions, like adding cloud.namespace attribute to the data. If you don't want this to happen, you should explicitly disable these functionalities:

processors:
  sumologic_schema:
    add_cloud_namespace: false
    # ...

Full list of configuration settings can be found in the readme of the processor.

sumologic exporter: drop support for translating Telegraf metric names

Similar as above, the translation should not happen in the exporter and has been moved to the sumologicschema processor. The functionality is now deprecated and will be removed soon.

However, if the attributes are not translated, some Sumo Logic apps might not work correctly. To migrate, add a sumologicschema processor to your pipelines that use the sumologic exporter and disable that functionality in the exporter:

processors:
  # ...
  sumologic_schema:
    translate_telegraf_attributes: true

exporters:
  sumologic:
    # ...
    translate_telegraf_attributes: false

# ...

service:
  pipelines:
    logs:
      processors:
        # - ...
        - sumologic_schema

Note: By default, the sumologicschema processor also performs other actions. Please see a corresponding warning in paragraph sumologic exporter: drop support for translating attributes for more information.

Upgrading to v0.55.0-sumo-0

filter processor: drop support for expr language

Expr language is supported by logstransform processor, so there is no need to have this functionality in filter processor.

The following configuration of filter processor:

processors:
  filter:
    logs:
      include:
        match_type: expr
        expressions:
          - Body matches "log to include"
      exclude:
        match_type: expr
        expressions:
          - Body matches "log to exclude"

is equivalent of the following configuration of logstransform processor:

processors:
  logstransform:
    operators:
      - type: filter
        expr: 'body matches "log to include"'
      - type: filter
        expr: 'not(body matches "log to exclude")'

Upgrading to v0.52.0-sumo-0

sumologic exporter: Removed carbon2 and graphite metric formats

These metric formats don't offer any advantages over Prometheus or OTLP formats. To migrate, simply switch the format to prometheus.

exporters:
  sumologic:
    metric_format: prometheus

Upgrading to v0.51.0-sumo-0

k8s_tagger processor: removed clusterName metadata extraction option

Before v0.51.0-sumo-0, you could specify clusterName as one of the options for metadata extraction:

processors:
  k8s_tagger:
    extract:
      metadata:
      - clusterName

Starting with v0.51.0-sumo-0, the clusterName option is removed. This is a result of an upstream change that removes the k8s.cluster.name metadata (link), which in turn is a result of Kubernetes libraries removing support for this deprecated and non-functional field (link).

How to upgrade

Check if you are using the extract.metadata option in your k8s_tagger processor configuration and if yes, check if it includes the clusterName entry. If it does, remove it.

For example, change the following configuration:

processors:
  k8s_tagger:
    extract:
      metadata:
      - clusterName
      - deploymentName
      - podName
      - serviceName
      - statefulSetName

to the following, removing the clusterName entry from the list:

processors:
  k8s_tagger:
    extract:
      metadata:
      - deploymentName
      - podName
      - serviceName
      - statefulSetName

sumologic exporter: metadata translation: changed the attribute that is translated to _sourceName from file.path.resolved to log.file.path_resolved

This change should have landed already in previous version v0.49.0-sumo-0. It is a result of a change in Filelog receiver, which starting with v0.49.0, changed the names of the attributes it creates when one of the configuration properties is set to true:

  • include_file_name: changed attribute name from file.name to log.file.name
  • include_file_name_resolved: changed attribute name from file.name.resolved to log.file.name_resolved
  • include_file_path: changed attribute name from file.path to log.file.path
  • include_file_path_resolved: changed attribute name from file.path.resolved to log.file.path_resolved

See documentation that describes this change.

How to upgrade

This change is technically a breaking change, but it should be transparent and require no changes in your configuration.

If you have a pipeline that includes Filelog receiver (configured with include_file_path_resolved: true) and Sumo Logic exporter, the Filelog receiver will create the log.file.path_resolved attribute and Sumo Logic exporter will translate this attribute to _sourceName.

exporters:
  sumologic:
    endpoint: ...

receivers:
  filelog:
    include:
    - ...
    include_file_path_resolved: true

service:
  pipelines:
    logs:
      exporters:
      - sumologic
      receivers:
      - filelog

In the unlikely scenario that you have a component other than Filelog receiver that creates the file.path.resolved attribute that you relied on Sumo Logic exporter to be translated to _sourceName attribute, you can perform the translation with Resource processor like the following:

processors:
  resource:
    attributes:
    - action: insert
      from_attribute: file.path.resolved
      key: _sourceName
    - action: delete
      key: file.path.resolved

Upgrading to 0.49.0-sumo-0

Several changes to receivers using opentelemetry-log-collection

The affected receivers are: filelog, syslog, tcplog, udplog, and journald.

opentelemetry-log-collection is a shared library used by the aforementioned receivers. This release contains several breaking changes to its configuration syntax. Please refer to the official upgrade guide for more information.

Sumo Logic exporter metadata handling

The OpenTelemetry data format makes a distinction between record-level attributes and resource-level attributes. The metadata_attributes configuration option in the sumologicexporter allowed setting metadata for records sent to the Sumo Logic backend based on both record and resource-level attributes. Only attributes matching the supplied regular expressions were sent.

However, this is conceptually incompatible with OpenTelemetry. Our intent with the exporter is to use OpenTelemetry conventions as much as we can, to the point where it should eventually be possible to export data to Sumo using the upstream OTLP exporter. This is why we are changing the behaviour. From now on:

  1. metadata_attributes no longer exists.
  2. Metadata for sent records is based on resource-level attributes.

In order to retain current behaviour, processors should be used to transform the data before it is exported. This potentially involves two transformations:

Removing unnecessary metadata using the resourceprocessor

metadata_attributes allowed filtering based on regular expressions. An equivalent processor doesn't yet exist, but resource-level attributed can be dropped using the resourceprocessor. For example:

processors:
  resource:
    attributes:
      - pattern: ^k8s\.pod\..*
        action: delete

will delete all attributes starting with k8s.pod..

NOTE: The ability to delete attributes based on a regular expression is currently unique to our fork of the resourceprocessor, and isn't available in upstream.

Moving record-level attributes used for metadata to the resource level

This can be done using the Group by Attributes processor. If you were using the Sumo Logic exporter to export data with a host record-level attribute:

exporters:
  sumologicexporter:
    ...
    metadata_attributes:
      - host

You can achieve the same effect with the following processor configuration:

processors:
  groupbyattrsprocessor:
    keys:
      - host

Keep in mind that your attribute may already be resource-level, in which case no changes are necessary.