feat: Rename awslogsencodingextension format values to shorter, more concise identifiers

.chloggen/feat_rename-awslogsencodingextension-format-names.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: deprecation
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: awslogsencodingextension
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Rename awslogsencodingextension format values to shorter, more concise identifiers. Old format values are still supported until v0.138.0.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [42901]
+
+# (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: []

extension/encoding/awslogsencodingextension/README.md

@@ -29,7 +29,7 @@ Example for Amazon CloudWatch Logs Subscription Filters:
 ```yaml
 extensions:
   awslogs_encoding/cloudwatch:
-    format: cloudwatch_logs_subscription_filter
+    format: cloudwatch
 
 receivers:
   awsfirehose:
@@ -40,9 +40,9 @@ receivers:
 Example for VPC flow logs:
 ```yaml
 extensions:
-  awslogs_encoding/vpc_flow_log:
-    format: vpc_flow_log
-    vpc_flow_log:
+  awslogs_encoding/vpcflow:
+    format: vpcflow
+    vpcflow:
       # options [parquet, plain-text]. 
       # parquet option still needs to be implemented.
       file_format: plain-text 
@@ -51,29 +51,70 @@ extensions:
 Example for S3 access logs:
 ```yaml
 extensions:
-  awslogs_encoding/s3_access_log:
-    format: s3_access_log
+  awslogs_encoding/s3access:
+    format: s3access
 ```
 
 Example for CloudTrail logs:
 ```yaml
 extensions:
   awslogs_encoding/cloudtrail:
-    format: cloudtrail_log
+    format: cloudtrail
 ```
 
 Example for ELB access logs:
 ```yaml
 extensions:
-  awslogs_encoding/elb_access_log:
-    format: elb_access_log
+  awslogs_encoding/elbaccess:
+    format: elbaccess
 ```
 
 ## Log Format Identification
 
-All logs processed by this extension are automatically tagged with an `awslogs_encoding.format` attribute at the scope level to identify the source format.
+All logs processed by this extension are automatically tagged with an `encoding.format` attribute at the scope level to identify the source format. This allows you to easily filter and route logs based on their AWS service origin.
 
-#### VPC flow log record fields
+The pattern used is `aws.<format_name>`.
+
+Examples:
+- VPC Flow Logs: `encoding.format:"aws.vpcflow"`
+- ELB Access Logs: `encoding.format:"aws.elbaccess"`
+
+## Format Values
+
+The following format values are supported in the `awslogsencodingextension` to identify different AWS log types:
+
+| **AWS Log Type** | **Format Value** | **Description** |
+|------------------|------------------|-----------------|
+| VPC Flow Logs | `vpcflow` | Virtual Private Cloud flow log records |
+| ELB Access Logs | `elbaccess` | Elastic Load Balancer access logs (ALB, NLB, CLB) |
+| S3 Access Logs | `s3access` | Amazon S3 server access logs |
+| CloudTrail Logs | `cloudtrail` | AWS CloudTrail API call logs |
+| WAF Logs | `waf` | AWS Web Application Firewall logs |
+| CloudWatch Logs | `cloudwatch` | CloudWatch Logs Subscription Filter events |
+
+### Breaking Change Notice
+
+**Format values have been simplified in v0.137.0**
+
+**The old format values are deprecated and will be unsupported in v0.138.0.**
+
+| **AWS Log Type** | **Old Format Value (Deprecated)** | **New Format Value** |
+|------------------|-----------------------------------|---------------------|
+| VPC Flow Logs | `vpc_flow_log` | `vpcflow` |
+| ELB Access Logs | `elb_access_log` | `elbaccess` |
+| S3 Access Logs | `s3_access_log` | `s3access` |
+| CloudTrail Logs | `cloudtrail_log` | `cloudtrail` |
+| WAF Logs | `waf_log` | `waf` |
+| CloudWatch Logs | `cloudwatch_logs_subscription_filter` | `cloudwatch` |
+
+#### Migration Path
+
+If you're using the old format values you should update the encoding extension configuration with the new format values.
+
+
+## Produced Records per Format
+
+### VPC flow log record fields
 
 [VPC flow log record fields](https://docs.aws.amazon.com/vpc/latest/userguide/flow-log-records.html#flow-logs-fields) are mapped this way in the resulting OpenTelemetry log:
 
@@ -120,7 +161,7 @@ All logs processed by this extension are automatically tagged with an `awslogs_e
 | `ecs-task-id`                | `aws.ecs.task.id`                                                                                     |
 | `reject-reason`              | `aws.vpc.flow.reject_reason`                                                                          |
 
-#### S3 access log record fields
+### S3 access log record fields
 
 [S3 access log record fields](https://docs.aws.amazon.com/AmazonS3/latest/userguide/LogFormat.html) are mapped this way in the resulting OpenTelemetry log:
 
@@ -153,7 +194,7 @@ All logs processed by this extension are automatically tagged with an `awslogs_e
 | TLS version         | `tls.protocol.version`                                                                                                                                                                                                                                                                                  |
 | Access point ARN    | `aws.s3.access_point.arn`                                                                                                                                                                                                                                                                               |
 | aclRequired         | `aws.s3.acl_required`                                                                                                                                                                                                                                                                                   |
-#### AWS WAF log record fields
+### AWS WAF log record fields
 
 [AWS WAF log record fields](https://docs.aws.amazon.com/waf/latest/developerguide/logging-fields.html) are mapped this way in the resulting OpenTelemetry log:
 
@@ -192,7 +233,7 @@ All logs processed by this extension are automatically tagged with an `awslogs_e
 | `challengeResponse`           | _Currently not supported_                                                                        |
 | `oversizeFields`              | _Currently not supported_                                                                        |
 
-#### CloudTrail log record fields
+### CloudTrail log record fields
 
 [CloudTrail log record fields](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-record-contents.html) are mapped this way in the resulting OpenTelemetry log:
 
@@ -232,11 +273,11 @@ All logs processed by this extension are automatically tagged with an `awslogs_e
 
 All request parameters and response elements are included directly as nested maps in the attributes, preserving their original structure.
 
-#### ELB Access Log Fields
+### ELB Access Log Fields
 
 ELB access log record fields are mapped this way in the resulting OpenTelemetry log:
 
-##### Application Load Balancer (ALB)
+#### Application Load Balancer (ALB)
 
 > AWS Fields are according to [documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-access-logs.html).
 
@@ -274,7 +315,7 @@ ELB access log record fields are mapped this way in the resulting OpenTelemetry
 | "classification_reason"      | _Currently not supported_                                |
 | conn_trace_id                | _Currently not supported_                                |
 
-##### Network Load Balancer (NLB)
+#### Network Load Balancer (NLB)
 
 > AWS Fields are according to [documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest//network/load-balancer-access-logs.html#access-log-entry-format).
 
@@ -303,7 +344,7 @@ ELB access log record fields are mapped this way in the resulting OpenTelemetry
 | alpn_client_preference_list  | _Currently not supported_                                   |
 | tls_connection_creation_time | _Currently not supported_                                   |
 
-##### Classic Load Balancer (CLB)
+#### Classic Load Balancer (CLB)
 
 > AWS Fields are according to [documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/access-log-collection.html)
 

extension/encoding/awslogsencodingextension/config.go

@@ -16,12 +16,20 @@ var _ xconfmap.Validator = (*Config)(nil)
 
 var (
 	supportedLogFormats = []string{
+		// New format values
 		constants.FormatCloudWatchLogsSubscriptionFilter,
 		constants.FormatVPCFlowLog,
 		constants.FormatS3AccessLog,
 		constants.FormatWAFLog,
 		constants.FormatCloudTrailLog,
 		constants.FormatELBAccessLog,
+		// Legacy format values (for backward compatibility)
+		constants.FormatCloudWatchLogsSubscriptionFilterV1,
+		constants.FormatVPCFlowLogV1,
+		constants.FormatS3AccessLogV1,
+		constants.FormatWAFLogV1,
+		constants.FormatCloudTrailLogV1,
+		constants.FormatELBAccessLogV1,
 	}
 	supportedVPCFlowLogFileFormat = []string{constants.FileFormatPlainText, constants.FileFormatParquet}
 )
@@ -30,16 +38,18 @@ type Config struct {
 	// Format defines the AWS logs format.
 	//
 	// Current valid values are:
-	// - cloudwatch_logs_subscription_filter
-	// - vpc_flow_log
-	// - s3_access_log
-	// - waf_log
-	// - cloudtrail_log
-	// - elb_access_log
+	// - cloudwatch
+	// - vpcflow
+	// - s3access
+	// - waf
+	// - cloudtrail
+	// - elbaccess
 	//
 	Format string `mapstructure:"format"`
 
-	VPCFlowLogConfig VPCFlowLogConfig `mapstructure:"vpc_flow_log"`
+	VPCFlowLogConfig VPCFlowLogConfig `mapstructure:"vpcflow"`
+	// Deprecated: use VPCFlowLogConfig instead. It will be removed in v0.138.0
+	VPCFlowLogConfigV1 VPCFlowLogConfig `mapstructure:"vpc_flow_log"`
 
 	// prevent unkeyed literal initialization
 	_ struct{}
@@ -63,10 +73,16 @@ func (cfg *Config) Validate() error {
 	case "":
 		errs = append(errs, fmt.Errorf("format unspecified, expected one of %q", supportedLogFormats))
 	case constants.FormatCloudWatchLogsSubscriptionFilter: // valid
+	case constants.FormatCloudWatchLogsSubscriptionFilterV1: // valid
+	case constants.FormatVPCFlowLogV1: // valid
 	case constants.FormatVPCFlowLog: // valid
+	case constants.FormatS3AccessLogV1: // valid
 	case constants.FormatS3AccessLog: // valid
+	case constants.FormatWAFLogV1: // valid
 	case constants.FormatWAFLog: // valid
+	case constants.FormatCloudTrailLogV1: // valid
 	case constants.FormatCloudTrailLog: // valid
+	case constants.FormatELBAccessLogV1: // valid
 	case constants.FormatELBAccessLog: // valid
 	default:
 		errs = append(errs, fmt.Errorf("unsupported format %q, expected one of %q", cfg.Format, supportedLogFormats))
@@ -83,6 +99,18 @@ func (cfg *Config) Validate() error {
 		))
 	}
 
+	// to be deprecated in v0.138.0
+	switch cfg.VPCFlowLogConfigV1.FileFormat {
+	case constants.FileFormatParquet: // valid
+	case constants.FileFormatPlainText: // valid
+	default:
+		errs = append(errs, fmt.Errorf(
+			"unsupported file format %q for VPC flow log, expected one of %q",
+			cfg.VPCFlowLogConfigV1.FileFormat,
+			supportedVPCFlowLogFileFormat,
+		))
+	}
+
 	if len(errs) > 0 {
 		return errors.Join(errs...)
 	}

extension/encoding/awslogsencodingextension/config_test.go

@@ -35,32 +35,60 @@ func TestLoadConfig(t *testing.T) {
 			expectedErr: fmt.Sprintf("format unspecified, expected one of %q", supportedLogFormats),
 		},
 		{
-			id: component.NewIDWithName(metadata.Type, "cloudwatch_logs_subscription_filter"),
+			id: component.NewIDWithName(metadata.Type, "cloudwatch"),
 			expected: &Config{
 				Format: constants.FormatCloudWatchLogsSubscriptionFilter,
 				VPCFlowLogConfig: VPCFlowLogConfig{
 					FileFormat: constants.FileFormatPlainText,
 				},
+				VPCFlowLogConfigV1: VPCFlowLogConfig{
+					FileFormat: constants.FileFormatPlainText,
+				},
 			},
 		},
 		{
-			id: component.NewIDWithName(metadata.Type, "text_vpc_flow_log"),
+			id: component.NewIDWithName(metadata.Type, "text_vpcflow"),
 			expected: &Config{
 				Format: constants.FormatVPCFlowLog,
 				VPCFlowLogConfig: VPCFlowLogConfig{
 					FileFormat: constants.FileFormatPlainText,
 				},
+				VPCFlowLogConfigV1: VPCFlowLogConfig{
+					FileFormat: constants.FileFormatPlainText,
+				},
+			},
+		},
+		{
+			id: component.NewIDWithName(metadata.Type, "text_vpc_flow_log"),
+			expected: &Config{
+				Format: constants.FormatVPCFlowLogV1,
+				VPCFlowLogConfigV1: VPCFlowLogConfig{
+					FileFormat: constants.FileFormatPlainText,
+				},
+				VPCFlowLogConfig: VPCFlowLogConfig{
+					FileFormat: constants.FileFormatPlainText,
+				},
 			},
 		},
 		{
-			id: component.NewIDWithName(metadata.Type, "parquet_vpc_flow_log"),
+			id: component.NewIDWithName(metadata.Type, "parquet_vpcflow"),
 			expected: &Config{
 				Format: constants.FormatVPCFlowLog,
 				VPCFlowLogConfig: VPCFlowLogConfig{
 					FileFormat: constants.FileFormatParquet,
 				},
+				VPCFlowLogConfigV1: VPCFlowLogConfig{
+					FileFormat: constants.FileFormatPlainText,
+				},
 			},
 		},
+		{
+			id: component.NewIDWithName(metadata.Type, "invalid_vpcflow"),
+			expectedErr: fmt.Sprintf(
+				`unsupported file format "invalid" for VPC flow log, expected one of %q`,
+				supportedVPCFlowLogFileFormat,
+			),
+		},
 		{
 			id: component.NewIDWithName(metadata.Type, "invalid_vpc_flow_log"),
 			expectedErr: fmt.Sprintf(
@@ -69,39 +97,51 @@ func TestLoadConfig(t *testing.T) {
 			),
 		},
 		{
-			id: component.NewIDWithName(metadata.Type, "s3_access_log"),
+			id: component.NewIDWithName(metadata.Type, "s3access"),
 			expected: &Config{
 				Format: constants.FormatS3AccessLog,
 				VPCFlowLogConfig: VPCFlowLogConfig{
 					FileFormat: constants.FileFormatPlainText,
 				},
+				VPCFlowLogConfigV1: VPCFlowLogConfig{
+					FileFormat: constants.FileFormatPlainText,
+				},
 			},
 		},
 		{
-			id: component.NewIDWithName(metadata.Type, "waf_log"),
+			id: component.NewIDWithName(metadata.Type, "waf"),
 			expected: &Config{
 				Format: constants.FormatWAFLog,
 				VPCFlowLogConfig: VPCFlowLogConfig{
 					FileFormat: constants.FileFormatPlainText,
 				},
+				VPCFlowLogConfigV1: VPCFlowLogConfig{
+					FileFormat: constants.FileFormatPlainText,
+				},
 			},
 		},
 		{
-			id: component.NewIDWithName(metadata.Type, "cloudtrail_log"),
+			id: component.NewIDWithName(metadata.Type, "cloudtrail"),
 			expected: &Config{
 				Format: constants.FormatCloudTrailLog,
 				VPCFlowLogConfig: VPCFlowLogConfig{
 					FileFormat: constants.FileFormatPlainText,
 				},
+				VPCFlowLogConfigV1: VPCFlowLogConfig{
+					FileFormat: constants.FileFormatPlainText,
+				},
 			},
 		},
 		{
-			id: component.NewIDWithName(metadata.Type, "elb_access_log"),
+			id: component.NewIDWithName(metadata.Type, "elbaccess"),
 			expected: &Config{
 				Format: constants.FormatELBAccessLog,
 				VPCFlowLogConfig: VPCFlowLogConfig{
 					FileFormat: constants.FileFormatPlainText,
 				},
+				VPCFlowLogConfigV1: VPCFlowLogConfig{
+					FileFormat: constants.FileFormatPlainText,
+				},
 			},
 		},
 	}