diff --git a/.chloggen/geo_fields.yaml b/.chloggen/geo_fields.yaml new file mode 100755 index 0000000000..452a456333 --- /dev/null +++ b/.chloggen/geo_fields.yaml @@ -0,0 +1,17 @@ +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: new_component + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: geo + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add geo fields to attribute registry. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1033] + +# (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: diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index e4e6d6b430..35d7e1ad75 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -49,6 +49,7 @@ body: - area:file - area:gcp - area:gen-ai + - area:geo - area:go - area:graphql - area:hardware diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 4c9316ddf1..7ca9195edb 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -41,6 +41,7 @@ body: - area:file - area:gcp - area:gen-ai + - area:geo - area:go - area:graphql - area:hardware diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index e6e543158e..89ab5516f4 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -50,6 +50,7 @@ body: - area:file - area:gcp - area:gen-ai + - area:geo - area:go - area:graphql - area:hardware diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 35356a67cb..4d80dbfe2f 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -61,6 +61,7 @@ Currently, the following namespaces exist: - [File](file.md) - [GCP](gcp.md) - [Gen AI](gen-ai.md) +- [Geo](geo.md) - [Go](go.md) - [GraphQL](graphql.md) - [Hardware](hardware.md) diff --git a/docs/attributes-registry/geo.md b/docs/attributes-registry/geo.md new file mode 100644 index 0000000000..64440ee478 --- /dev/null +++ b/docs/attributes-registry/geo.md @@ -0,0 +1,34 @@ + + + + + +# Geo + +## Geo Attributes + +Geo fields can carry data about a specific location related to an event. This geolocation information can be derived from techniques such as Geo IP, or be user-supplied. +Note: Geo attributes are typically used under another namespace, such as client.* and describe the location of the corresponding entity (device, end-user, etc). Semantic conventions that reference geo attributes (as a root namespace) or embed them (under their own namespace) SHOULD document what geo attributes describe in the scope of that convention. + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `geo.continent.code` | string | Two-letter code representing continent’s name. | `AF`; `AN`; `AS` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `geo.country.iso_code` | string | Two-letter ISO Country Code ([ISO 3166-1 alpha2](https://en.wikipedia.org/wiki/ISO_3166-1#Codes)). | `CA` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `geo.locality.name` | string | Locality name. Represents the name of a city, town, village, or similar populated place. | `Montreal`; `Berlin` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `geo.location.lat` | double | Latitude of the geo location in [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84). | `45.505918` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `geo.location.lon` | double | Longitude of the geo location in [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84). | `-73.61483` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `geo.postal_code` | string | Postal code associated with the location. Values appropriate for this field may also be known as a postcode or ZIP code and will vary widely from country to country. | `94040` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `geo.region.iso_code` | string | Region ISO code ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)). | `CA-QC` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`geo.continent.code` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `AF` | Africa | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `AN` | Antarctica | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `AS` | Asia | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `EU` | Europe | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `NA` | North America | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `OC` | Oceania | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `SA` | South America | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/geo/registry.yaml b/model/geo/registry.yaml new file mode 100644 index 0000000000..41cb4afb38 --- /dev/null +++ b/model/geo/registry.yaml @@ -0,0 +1,83 @@ +groups: + - id: registry.geo + type: attribute_group + brief: > + Geo fields can carry data about a specific location related to an event. + This geolocation information can be derived from techniques such as Geo IP, or be user-supplied. + + Note: Geo attributes are typically used under another namespace, such as client.* and describe the location of the corresponding + entity (device, end-user, etc). Semantic conventions that reference geo attributes (as a root namespace) or embed them + (under their own namespace) SHOULD document what geo attributes describe in the scope of that convention. + + attributes: + - id: geo.locality.name + stability: experimental + type: string + brief: > + Locality name. Represents the name of a city, town, village, or similar populated place. + examples: [ 'Montreal', 'Berlin' ] + - id: geo.continent.code + stability: experimental + brief: > + Two-letter code representing continent’s name. + type: + members: + - id: 'af' + stability: experimental + value: 'AF' + brief: 'Africa' + - id: 'an' + stability: experimental + value: 'AN' + brief: 'Antarctica' + - id: 'as' + stability: experimental + value: 'AS' + brief: 'Asia' + - id: 'eu' + stability: experimental + value: 'EU' + brief: 'Europe' + - id: 'na' + stability: experimental + value: 'NA' + brief: 'North America' + - id: 'oc' + stability: experimental + value: 'OC' + brief: 'Oceania' + - id: 'sa' + stability: experimental + value: 'SA' + brief: 'South America' + - id: geo.country.iso_code + stability: experimental + type: string + brief: > + Two-letter ISO Country Code ([ISO 3166-1 alpha2](https://en.wikipedia.org/wiki/ISO_3166-1#Codes)). + examples: [ 'CA' ] + - id: geo.location.lon + stability: experimental + type: double + brief: > + Longitude of the geo location in [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84). + examples: [ -73.614830 ] + - id: geo.location.lat + stability: experimental + type: double + brief: > + Latitude of the geo location in [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84). + examples: [ 45.505918 ] + - id: geo.postal_code + stability: experimental + type: string + brief: > + Postal code associated with the location. + Values appropriate for this field may also be known as a postcode or ZIP code and will vary widely from country to country. + examples: [ '94040' ] + - id: geo.region.iso_code + stability: experimental + type: string + brief: > + Region ISO code ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)). + examples: [ 'CA-QC' ]