[translator/azurelogs] Rethink log structure, and define resource attributes

[constanca-m]

Component(s)

pkg/translator/azurelogs

Describe the issue you're reporting

Consider this example log:

{
    "records": [
        {
            "time": "2024-04-24T12:06:12.0000000Z",
            "resourceId": "/firstResource",
            "category": "firstResource",
            "operationName": "firstResource"
        },
        {
            "time": "2024-04-24T12:06:12.0000000Z",
            "resourceId": "/firstResource",
            "category": "firstResource",
            "operationName": "firstResource"
        },
        {
            "time": "2024-04-24T12:06:12.0000000Z",
            "resourceId": "/secondResource",
            "category": "secondResource",
            "operationName": "secondResource"
        }
    ]
}

The expectation for this would be to have two resources: one for resource /firstResource, and the other for resource /secondResource. These resourceId would fit resource attributes best:

A resource represents the entity producing telemetry as resource attributes. [source]

Description: Describes the source of the log, aka resource. Multiple occurrences of events coming from the same event source can happen across time and they all have the same value of Resource. [...] Data formats that represent this data model may be designed in a manner that allows the Resource field to be recorded only once per batch of log records that come from the same source. [source]

Rather, the properties of these records should be log record attributes (these are not pictured in the example file above). Category and operation name could be as well resource attributes.

These are the produced logs:

resourceLogs:
  - resource: {}
    scopeLogs:
      - logRecords:
          - attributes:
              - key: cloud.resource_id
                value:
                  stringValue: /firstResource
              - key: cloud.provider
                value:
                  stringValue: azure
              - key: event.name
                value:
                  stringValue: az.resource.log
            body: [...]
            spanId: ""
            timeUnixNano: "1713960372000000000"
            traceId: ""
          - attributes:
              - key: cloud.resource_id
                value:
                  stringValue: /firstResource
              - key: cloud.provider
                value:
                  stringValue: azure
              - key: event.name
                value:
                  stringValue: az.resource.log
            body: [...]
            spanId: ""
            timeUnixNano: "1713960372000000000"
            traceId: ""
        scope:
          name: otelcol/azureresourcelogs
          version: 1.2.3
  - resource: {}
    scopeLogs:
      - logRecords:
          - attributes:
              - key: cloud.resource_id
                value:
                  stringValue: /secondResource
              - key: cloud.provider
                value:
                  stringValue: azure
              - key: event.name
                value:
                  stringValue: az.resource.log
            body: [...]
            spanId: ""
            timeUnixNano: "1713960372000000000"
            traceId: ""
        scope:
          name: otelcol/azureresourcelogs
          version: 1.2.3

Even though it is correct that we have two resources, these resources have empty attributes, and the attributes of the log record are the resource attributes.

The properties (placed inside the body) could then be the actual log record attributes. See for example the AWS VPC flow log to get a better idea.

At the moment, inside the body we have a kvlistValue field:

body:
  kvlistValue:
    values:
      - key: operation.name
        value:
          stringValue: Authorization
      - key: enduser.id
        value:
          stringValue: USER_ID
      - key: client.address
        value:
          stringValue: 42.42.42.42
      - key: network.protocol.name
        value:
          stringValue: kudu
      - key: properties
        value:
          kvlistValue:
            values:
              - key: UserDisplayName
                value:
                  stringValue: $fbehtestapp
      - key: category
        value:
          stringValue: AppServiceAuditLogs

Which maybe is unconventional, and would fit best in the log record attributes.

[constanca-m]

Pinging code owners: @atoulme, @cparkins, @MikeGoldsmith (as this didn't get done automatically).

[constanca-m]

/label pkg/translator/azurelogs

[github-actions]

Pinging code owners for pkg/translator/azurelogs: @atoulme @cparkins @MikeGoldsmith. See Adding Labels via Comments if you do not have permissions to add labels yourself. For example, comment '/label priority:p2 -needs-triaged' to set the priority and remove the needs-triaged label.

[constanca-m]

I think resources without attributes should be even considered a bug at this point. Resources with the same attributes (or in this case, without any attributes) are considered the same, and this is obviously not the case. You can find this issue manifesting in our unit tests log_maximum: we have two resources, but they can be placed in a different order in the expected file. Because the two resources are the same, we have an error that only happens sometimes:

Received unexpected error:
	            	the following errors occurred:
	            	 -  resource "map[]": scope "otelcol/azureresourcelogs": number of log records doesn't match expected: 1, actual: 2
	            	 -  resource "map[]": scope "otelcol/azureresourcelogs": number of log records doesn't match expected: 2, actual: 1
	Test:       	TestUnmarshalLogs_Files/log_maximum

See the logs comparison function for better understanding.

cc @atoulme @MikeGoldsmith @cparkins

[constanca-m]

/label bug

[atoulme]

@cparkins what's your take?

[cparkins]

@atoulme I have no reason to disagree. But how logs should be structured is not something I have much of an educated opinion on. I think what is being proposed makes sense.

[atoulme]

Thanks @cparkins @constanca-m take it away (and feel free to make yourself a codeowner)

[constanca-m]

Thanks @atoulme , I will open a request for codeowner later this week.

I will wait for #39340 to be merged before starting to work on this, so that the number of PRs opened stays low.