[receiver/github] add repository custom properties as resource attributes

.chloggen/githubreceiver-add-repository-custom-properties.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: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: githubreceiver
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Added the ability to convert custom repository properties to span attributes
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [40878]
+
+# (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]

receiver/githubreceiver/README.md

@@ -24,6 +24,7 @@
   - [Receiver Configuration](#receiver-configuration)
   - [Configuring Service Name](#configuring-service-name)
   - [Configuration a GitHub App](#configuration-a-github-app)
+  - [Custom Properties as Resource Attributes](#custom-properties-as-resource-attributes)
 
 ## Overview
 
@@ -220,3 +221,51 @@ create a GitHub App. During the subscription phase, subscribe to `workflow_run`
 [run]: https://github.com/krzko/run-with-telemetry
 [otcli]: https://github.com/equinix-labs/otel-cli
 [tr]: ./trace_event_handling.go
+
+### Custom Properties as Resource Attributes
+
+The GitHub receiver supports adding custom properties from GitHub repositories as resource attributes in your telemetry data. This allows users to enrich traces and events with additional metadata specific to each repository.
+
+#### How It Works
+
+When a GitHub webhook event is received, the receiver extracts all custom properties from the repository and adds them as resource attributes with the prefix `github.repository.custom_properties`.
+
+For example, if your repository has these custom properties:
+
+```
+classification: public
+service-tier: critical
+slack-support-channel: #observability-alerts
+team-name: observability-engineering
+```
+
+They will be added as resource attributes:
+
+```
+github.repository.custom_properties.classification: "public"
+github.repository.custom_properties.service_tier: "critical"
+github.repository.custom_properties.slack_support_channel: "#observability-alerts"
+github.repository.custom_properties.team_name: "observability-engineering"
+```
+
+#### Key Formatting
+
+To ensure consistency with OpenTelemetry naming conventions, all custom property keys are converted to snake_case format using the following rules:
+
+1. Hyphens, spaces, and dots are replaced with underscores
+2. Special characters like `$` and `#` are replaced with `_dollar_` and `_hash_`
+3. CamelCase and PascalCase are converted to snake_case by inserting underscores before uppercase letters
+4. Multiple consecutive underscores are replaced with a single underscore
+
+Examples of key transformations:
+
+| Original Key | Transformed Key |
+|--------------|----------------|
+| `teamName` | `team_name` |
+| `API-Key` | `api_key` |
+| `Service.Level` | `service_level` |
+| `$Cost` | `_dollar_cost` |
+| `#Priority` | `_hash_priority` |
+
+**Note**:
+The `service_name` custom property is handled specially and is not added as a resource attribute with the prefix. Instead, it's used to set the `service.name` resource attribute directly, as described in the [Configuring Service Name](#configuring-service-name) section.

receiver/githubreceiver/model.go

@@ -5,7 +5,9 @@ package githubreceiver // import "github.com/open-telemetry/opentelemetry-collec
 
 import (
 	"errors"
+	"fmt"
 	"strings"
+	"unicode"
 
 	"github.com/google/go-github/v72/github"
 	"go.opentelemetry.io/collector/pdata/pcommon"
@@ -105,6 +107,7 @@ const (
 	// The following attributes are exclusive to GitHub but not listed under
 	// Vendor Extensions within Semantic Conventions yet.
 	AttributeGitHubAppInstallationID            = "github.app.installation.id"             // GitHub's Installation ID
+	AttributeGitHubRepositoryCustomProperty     = "github.repository.custom_properties"    // GitHub's Repository Custom Properties
 	AttributeGitHubWorkflowRunAttempt           = "github.workflow.run.attempt"            // GitHub's Run Attempt
 	AttributeGitHubWorkflowTriggerActorUsername = "github.workflow.trigger.actor.username" // GitHub's Triggering Actor Username
 
@@ -147,6 +150,9 @@ func (gtr *githubTracesReceiver) getWorkflowRunAttrs(resource pcommon.Resource,
 
 	attrs.PutStr(string(semconv.ServiceNameKey), svc)
 
+	// Add all custom properties from the repository as resource attributes
+	addCustomPropertiesToAttrs(attrs, e.GetRepo().CustomProperties)
+
 	// VCS Attributes
 	attrs.PutStr(AttributeVCSRepositoryName, e.GetRepo().GetName())
 	attrs.PutStr(AttributeVCSVendorName, "github")
@@ -220,6 +226,9 @@ func (gtr *githubTracesReceiver) getWorkflowJobAttrs(resource pcommon.Resource,
 
 	attrs.PutStr(string(semconv.ServiceNameKey), svc)
 
+	// Add all custom properties from the repository as resource attributes
+	addCustomPropertiesToAttrs(attrs, e.GetRepo().CustomProperties)
+
 	// VCS Attributes
 	attrs.PutStr(AttributeVCSRepositoryName, e.GetRepo().GetName())
 	attrs.PutStr(AttributeVCSVendorName, "github")
@@ -317,6 +326,45 @@ func (gtr *githubTracesReceiver) getServiceName(customProps any, repoName string
 	}
 }
 
+// addCustomPropertiesToAttrs adds all custom properties from the repository as resource attributes
+// with the prefix AttributeGitHubCustomProperty. Keys are converted to snake_case to follow
+// resource attribute naming convention.
+func addCustomPropertiesToAttrs(attrs pcommon.Map, customProps map[string]any) {
+	if len(customProps) == 0 {
+		return
+	}
+
+	for key, value := range customProps {
+		// Skip service_name as it's already handled separately
+		if key == "service_name" {
+			continue
+		}
+
+		// Convert key to snake_case
+		snakeCaseKey := toSnakeCase(key)
+
+		// Use dot notation for keys, following resource attribute naming convention
+		attrKey := fmt.Sprintf("%s.%s", AttributeGitHubRepositoryCustomProperty, snakeCaseKey)
+
+		// Handle different value types
+		switch v := value.(type) {
+		case string:
+			attrs.PutStr(attrKey, v)
+		case int:
+			attrs.PutInt(attrKey, int64(v))
+		case int64:
+			attrs.PutInt(attrKey, v)
+		case float64:
+			attrs.PutDouble(attrKey, v)
+		case bool:
+			attrs.PutBool(attrKey, v)
+		default:
+			// For any other types, convert to string
+			attrs.PutStr(attrKey, fmt.Sprintf("%v", v))
+		}
+	}
+}
+
 // formatString formats a string to lowercase and replaces underscores with
 // hyphens.
 func formatString(input string) string {
@@ -328,3 +376,41 @@ func replaceAPIURL(apiURL string) (htmlURL string) {
 	// TODO: Support enterpise server configuration with custom domain.
 	return strings.Replace(apiURL, "api.github.com/repos", "github.com", 1)
 }
+
+// toSnakeCase converts a string to snake_case format.
+// It handles all GitHub supported characters for custom property names: a-z, A-Z, 0-9, _, -, $, #.
+// This function ensures that the resulting string follows snake_case convention.
+func toSnakeCase(s string) string {
+	// Replace hyphens, spaces, and dots with underscores
+	s = strings.ReplaceAll(s, "-", "_")
+	s = strings.ReplaceAll(s, " ", "_")
+	s = strings.ReplaceAll(s, ".", "_")
+
+	// Replace special characters with underscores
+	s = strings.ReplaceAll(s, "$", "_dollar_")
+	s = strings.ReplaceAll(s, "#", "_hash_")
+
+	// Handle camelCase and PascalCase
+	var result strings.Builder
+	for i, r := range s {
+		if i > 0 && unicode.IsUpper(r) {
+			// If current char is uppercase and previous char is lowercase or a digit,
+			// or if current char is uppercase and next char is lowercase,
+			// add an underscore before the current char
+			prevIsLower := i > 0 && (unicode.IsLower(rune(s[i-1])) || unicode.IsDigit(rune(s[i-1])))
+			nextIsLower := i < len(s)-1 && unicode.IsLower(rune(s[i+1]))
+			if prevIsLower || nextIsLower {
+				result.WriteRune('_')
+			}
+		}
+		result.WriteRune(unicode.ToLower(r))
+	}
+
+	// Replace multiple consecutive underscores with a single one
+	output := result.String()
+	for strings.Contains(output, "__") {
+		output = strings.ReplaceAll(output, "__", "_")
+	}
+
+	return output
+}

receiver/githubreceiver/model_test.go

@@ -7,6 +7,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+	"go.opentelemetry.io/collector/pdata/pcommon"
 )
 
 func TestFormatString(t *testing.T) {
@@ -123,3 +124,145 @@ func TestReplaceAPIURL(t *testing.T) {
 		})
 	}
 }
+
+func TestAddCustomPropertiesToAttrs(t *testing.T) {
+	tests := []struct {
+		name         string
+		customProps  map[string]any
+		expectedKeys []string
+		expectedVals map[string]any
+	}{
+		{
+			name: "adds string custom properties",
+			customProps: map[string]any{
+				"team_name":    "open-telemetry",
+				"environment":  "development",
+				"service_name": "should-be-skipped", // This should be skipped
+			},
+			expectedKeys: []string{
+				"github.repository.custom_properties.team_name",
+				"github.repository.custom_properties.environment",
+			},
+			expectedVals: map[string]any{
+				"github.repository.custom_properties.team_name":   "open-telemetry",
+				"github.repository.custom_properties.environment": "development",
+			},
+		},
+		{
+			name: "adds different types of custom properties",
+			customProps: map[string]any{
+				"string_prop": "string-value",
+				"int_prop":    42,
+				"float_prop":  3.14,
+				"bool_prop":   true,
+			},
+			expectedKeys: []string{
+				"github.repository.custom_properties.string_prop",
+				"github.repository.custom_properties.int_prop",
+				"github.repository.custom_properties.float_prop",
+				"github.repository.custom_properties.bool_prop",
+			},
+			expectedVals: map[string]any{
+				"github.repository.custom_properties.string_prop": "string-value",
+				"github.repository.custom_properties.int_prop":    int64(42),
+				"github.repository.custom_properties.float_prop":  3.14,
+				"github.repository.custom_properties.bool_prop":   true,
+			},
+		},
+		{
+			name: "converts keys to snake_case",
+			customProps: map[string]any{
+				"camelCase":   "camel-value",
+				"PascalCase":  "pascal-value",
+				"kebab-case":  "kebab-value",
+				"space case":  "space-value",
+				"mixed_Case":  "mixed-value",
+				"withNumber1": "number-value",
+				"with.dots":   "dots-value",
+				"$dollar":     "dollar-value",
+				"#hash":       "hash-value",
+			},
+			expectedKeys: []string{
+				"github.repository.custom_properties.camel_case",
+				"github.repository.custom_properties.pascal_case",
+				"github.repository.custom_properties.kebab_case",
+				"github.repository.custom_properties.space_case",
+				"github.repository.custom_properties.mixed_case",
+				"github.repository.custom_properties.with_number1",
+				"github.repository.custom_properties.with_dots",
+				"github.repository.custom_properties._dollar_dollar",
+				"github.repository.custom_properties._hash_hash",
+			},
+			expectedVals: map[string]any{
+				"github.repository.custom_properties.camel_case":     "camel-value",
+				"github.repository.custom_properties.pascal_case":    "pascal-value",
+				"github.repository.custom_properties.kebab_case":     "kebab-value",
+				"github.repository.custom_properties.space_case":     "space-value",
+				"github.repository.custom_properties.mixed_case":     "mixed-value",
+				"github.repository.custom_properties.with_number1":   "number-value",
+				"github.repository.custom_properties.with_dots":      "dots-value",
+				"github.repository.custom_properties._dollar_dollar": "dollar-value",
+				"github.repository.custom_properties._hash_hash":     "hash-value",
+			},
+		},
+		{
+			name:         "handles empty custom properties",
+			customProps:  map[string]any{},
+			expectedKeys: []string{},
+			expectedVals: map[string]any{},
+		},
+		{
+			name:         "handles nil custom properties",
+			customProps:  nil,
+			expectedKeys: []string{},
+			expectedVals: map[string]any{},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Create a new resource with empty attributes
+			resource := pcommon.NewResource()
+			attrs := resource.Attributes()
+
+			// Add custom properties to attributes
+			addCustomPropertiesToAttrs(attrs, tt.customProps)
+
+			// Check that all expected keys exist
+			for _, key := range tt.expectedKeys {
+				_, exists := attrs.Get(key)
+				assert.True(t, exists, "Expected key %s not found", key)
+			}
+
+			// Check that service_name is not added
+			_, exists := attrs.Get("github.repository.custom_properties.service_name")
+			assert.False(t, exists)
+
+			// Check values
+			for key, expectedVal := range tt.expectedVals {
+				switch expected := expectedVal.(type) {
+				case string:
+					val, _ := attrs.Get(key)
+					assert.Equal(t, expected, val.Str())
+				case int64:
+					val, _ := attrs.Get(key)
+					assert.Equal(t, expected, val.Int())
+				case float64:
+					val, _ := attrs.Get(key)
+					assert.Equal(t, expected, val.Double())
+				case bool:
+					val, _ := attrs.Get(key)
+					assert.Equal(t, expected, val.Bool())
+				}
+			}
+
+			// Check that no unexpected keys were added
+			count := 0
+			attrs.Range(func(_ string, _ pcommon.Value) bool {
+				count++
+				return true
+			})
+			assert.Equal(t, len(tt.expectedKeys), count)
+		})
+	}
+}

receiver/githubreceiver/testdata/workflow-job-expected.yaml

@@ -4,6 +4,9 @@ resourceSpans:
         - key: service.name
           value:
             stringValue: otel-collector
+        - key: github.repository.custom_properties.team_name
+          value:
+            stringValue: open-telemetry
         - key: vcs.repository.name
           value:
             stringValue: open-telemetry-otel-collector

receiver/githubreceiver/testdata/workflow-run-expected.yaml

@@ -4,6 +4,9 @@ resourceSpans:
         - key: service.name
           value:
             stringValue: otel-collector
+        - key: github.repository.custom_properties.team_name
+          value:
+            stringValue: open-telemetry
         - key: vcs.repository.name
           value:
             stringValue: open-telemetry-otel-collector