feat(otelschema): add semconv schema parser

go.mod

@@ -56,6 +56,7 @@ require (
 	golang.org/x/sync v0.5.0
 	golang.org/x/tools v0.15.0
 	google.golang.org/grpc v1.59.0
+	sigs.k8s.io/yaml v1.3.0
 )
 
 require (

internal/otelschema/_testdata/model/README.md

@@ -0,0 +1,41 @@
+# YAML Model for Semantic Conventions
+
+The YAML descriptions of semantic convention contained in this directory are intended to
+be used by the various OpenTelemetry language implementations to aid in automatic
+generation of semantics-related code.
+
+⚠ If you want to read the semantic conventions and not edit them, please see
+the generated markdown output in the [docs](../docs/README.md) folder.
+
+## Writing semantic conventions
+
+Semantic conventions for the spec MUST adhere to the
+[attribute naming](../docs/general/attribute-naming.md),
+[attribute requirement level](../docs/general/attribute-requirement-level.md),
+and [metric requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md) conventions.
+
+Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.23.0/semantic-conventions/syntax.md)
+for how to write the YAML files for semantic conventions and what the YAML properties mean.
+
+A schema file for VS code is configured in the `/.vscode/settings.json` of this
+repository, enabling auto-completion and additional checks. Refer to
+[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.23.0/semantic-conventions/README.md) for what extension you need.
+
+## Generating markdown
+
+These YAML files are used by the make target `table-generation` to generate consistently
+formatted Markdown tables for all semantic conventions in the specification. Run it from the root of this repository using the command
+
+```
+make table-generation
+```
+
+For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.23.0/semantic-conventions)
+in the OpenTelemetry build tools repository.
+Using this build tool, it is also possible to generate code for use in OpenTelemetry
+language projects.
+
+See also:
+
+* [Markdown Tables](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions#markdown-tables)
+* [Code Generator](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions#code-generator)

internal/otelschema/_testdata/model/exception.yaml

@@ -0,0 +1,33 @@
+groups:
+  - id: exception
+    type: span
+    prefix: exception
+    brief: >
+      This document defines the shared attributes used to
+      report a single exception associated with a span or log.
+    attributes:
+      - id: type
+        type: string
+        brief: >
+          The type of the exception (its fully-qualified class name, if applicable).
+          The dynamic type of the exception should be preferred over the static type
+          in languages that support it.
+        examples: ["java.net.ConnectException", "OSError"]
+      - id: message
+        type: string
+        brief: The exception message.
+        examples: ["Division by zero", "Can't convert 'int' object to str implicitly"]
+      - id: stacktrace
+        type: string
+        brief: >
+          A stacktrace as a string in the natural representation for the language runtime.
+          The representation is to be determined and documented by each language SIG.
+        examples: 'Exception in thread "main" java.lang.RuntimeException: Test exception\n
+        at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n
+        at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n
+        at com.example.GenerateTrace.main(GenerateTrace.java:5)'
+
+    constraints:
+      - any_of:
+          - "exception.type"
+          - "exception.message"

internal/otelschema/_testdata/model/faas-common.yaml

@@ -0,0 +1,77 @@
+groups:
+  - id: attributes.faas.common
+    type: attribute_group
+    brief: "Describes FaaS attributes."
+    prefix: faas
+    attributes:
+      - id: trigger
+        brief: 'Type of the trigger which caused this function invocation.'
+        type:
+          allow_custom_values: false
+          members:
+            - id: datasource
+              value: 'datasource'
+              brief: 'A response to some data source operation such as a database or filesystem read/write'
+            - id: http
+              value: 'http'
+              brief: 'To provide an answer to an inbound HTTP request'
+            - id: pubsub
+              value: 'pubsub'
+              brief: 'A function is set to be executed when messages are sent to a messaging system'
+            - id: timer
+              value: 'timer'
+              brief: 'A function is scheduled to be executed regularly'
+            - id: other
+              value: 'other'
+              brief: 'If none of the others apply'
+      - id: invoked_name
+        type: string
+        requirement_level: required
+        brief: >
+          The name of the invoked function.
+        note: >
+          SHOULD be equal to the `faas.name` resource attribute of the
+          invoked function.
+        examples: 'my-function'
+      - id: invoked_provider
+        type:
+          allow_custom_values: true
+          members:
+            - id: 'alibaba_cloud'
+              value: 'alibaba_cloud'
+              brief: 'Alibaba Cloud'
+            - id: 'aws'
+              value: 'aws'
+              brief: 'Amazon Web Services'
+            - id: 'azure'
+              value: 'azure'
+              brief: 'Microsoft Azure'
+            - id: 'gcp'
+              value: 'gcp'
+              brief: 'Google Cloud Platform'
+            - id: 'tencent_cloud'
+              value: 'tencent_cloud'
+              brief: 'Tencent Cloud'
+        requirement_level: required
+        brief: >
+          The cloud provider of the invoked function.
+        note: >
+          SHOULD be equal to the `cloud.provider` resource attribute of the
+          invoked function.
+      - id: invoked_region
+        type: string
+        requirement_level:
+          conditionally_required: >
+            For some cloud providers, like AWS or GCP, the region in which a
+            function is hosted is essential to uniquely identify the function
+            and also part of its endpoint. Since it's part of the endpoint
+            being called, the region is always known to clients. In these cases,
+            `faas.invoked_region` MUST be set accordingly. If the region is
+            unknown to the client or not required for identifying the invoked
+            function, setting `faas.invoked_region` is optional.
+        brief: >
+          The cloud region of the invoked function.
+        note: >
+          SHOULD be equal to the `cloud.region` resource attribute of the
+          invoked function.
+        examples: 'eu-central-1'

internal/otelschema/_testdata/model/general.yaml

@@ -0,0 +1,85 @@
+groups:
+  - id: general.client
+    type: attribute_group
+    brief: >
+      General client attributes.
+    attributes:
+      - ref: client.address
+      - ref: client.port
+  - id: general.server
+    type: attribute_group
+    brief: >
+      General server attributes.
+    attributes:
+      - ref: server.address
+      - ref: server.port
+  - id: general.source
+    type: attribute_group
+    brief: >
+      General source attributes.
+    attributes:
+      - ref: source.address
+      - ref: source.port
+  - id: general.destination
+    type: attribute_group
+    brief: >
+      General destination attributes.
+    attributes:
+      - ref: destination.address
+      - ref: destination.port
+  - id: peer
+    prefix: peer
+    type: span
+    brief: "Operations that access some remote service."
+    attributes:
+      - id: service
+        type: string
+        brief: >
+          The [`service.name`](/docs/resource/README.md#service)
+          of the remote service. SHOULD be equal to the actual `service.name`
+          resource attribute of the remote service if any.
+        examples: "AuthTokenCache"
+  - id: identity
+    prefix: enduser
+    type: span
+    brief: >
+      These attributes may be used for any operation with an authenticated and/or authorized enduser.
+    attributes:
+      - id: id
+        type: string
+        brief: >
+          Username or client_id extracted from the access token or
+          [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2)
+          header in the inbound request from outside the system.
+        examples: 'username'
+      - id: role
+        type: string
+        brief: 'Actual/assumed role the client is making the request under extracted from token or application security context.'
+        examples: 'admin'
+      - id: scope
+        type: string
+        brief: >
+          Scopes or granted authorities the client currently possesses extracted from token
+          or application security context. The value would come from the scope associated
+          with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3)
+          or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html).
+        examples: 'read:message, write:files'
+  - id: thread
+    type: span
+    brief: >
+      These attributes may be used for any operation to store information about a thread that started a span.
+    attributes:
+      - ref: thread.id
+      - ref: thread.name
+  - id: code
+    type: span
+    brief: >
+      These attributes allow to report this unit of code and therefore to provide more context about the span.
+    attributes:
+      - ref: code.function
+      - ref: code.namespace
+      - ref: code.filepath
+      - ref: code.lineno
+      - ref: code.column
+      - ref: code.stacktrace
+        requirement_level: opt_in

internal/otelschema/_testdata/model/http-common.yaml

@@ -0,0 +1,87 @@
+groups:
+  - id: attributes.http.common
+    type: attribute_group
+    brief: "Describes HTTP attributes."
+    attributes:
+      - ref: http.request.method
+        requirement_level: required
+      - ref: http.response.status_code
+        requirement_level:
+          conditionally_required: If and only if one was received/sent.
+      - ref: error.type
+        requirement_level:
+          conditionally_required: If request has ended with an error.
+        examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', '500']
+        note: |
+          If the request fails with an error before response status code was sent or received,
+          `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable)
+          or a component-specific low cardinality error identifier.
+
+          If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md),
+          `error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier.
+
+          The `error.type` value SHOULD be predictable and SHOULD have low cardinality.
+          Instrumentations SHOULD document the list of errors they report.
+
+          The cardinality of `error.type` within one instrumentation library SHOULD be low, but
+          telemetry consumers that aggregate data from multiple instrumentation libraries and applications
+          should be prepared for `error.type` to have high cardinality at query time, when no
+          additional filters are applied.
+
+          If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
+      - ref: network.protocol.name
+        examples: ['http', 'spdy']
+        requirement_level:
+          conditionally_required: If not `http` and `network.protocol.version` is set.
+      - ref: network.protocol.version
+        examples: ['1.0', '1.1', '2', '3']
+
+  - id: attributes.http.client
+    type: attribute_group
+    brief: 'HTTP Client attributes'
+    extends: attributes.http.common
+    attributes:
+      - ref: server.address
+        requirement_level: required
+        brief: >
+          Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to.
+        note: >
+          If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then
+          `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used.
+      - ref: server.port
+        requirement_level: required
+        brief: >
+          Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to.
+      - ref: url.scheme
+        requirement_level: opt_in
+        examples: ["http", "https"]
+
+  - id: attributes.http.server
+    type: attribute_group
+    brief: 'HTTP Server attributes'
+    extends: attributes.http.common
+    attributes:
+      - ref: http.route
+        requirement_level:
+          conditionally_required: If and only if it's available
+      - ref: server.address
+        brief: >
+          Name of the local HTTP server that received the request.
+        note: >
+          See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
+      - ref: server.port
+        brief: >
+          Port of the local HTTP server that received the request.
+        note: >
+          See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
+        requirement_level:
+          conditionally_required: If `server.address` is set.
+      - ref: url.scheme
+        requirement_level: required
+        examples: ["http", "https"]
+        note: >
+          The scheme of the original client request, if known
+          (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto),
+          [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto),
+          or a similar header).
+          Otherwise, the scheme of the immediate peer request.

internal/otelschema/_testdata/model/logs/events.yaml

@@ -0,0 +1,18 @@
+groups:
+  - id: event
+    type: attribute_group
+    prefix: event
+    brief: >
+        This document defines attributes for Events represented using Log Records.
+    attributes:
+      - id: name
+        type: string
+        requirement_level: required
+        brief: >
+          Identifies the class / type of event.
+        note: >
+          Event names are subject to the same rules as [attribute names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/common/attribute-naming.md).
+          Notably, event names are namespaced to avoid collisions and provide a clean
+          separation of semantics for events in separate domains like browser, mobile, and
+          kubernetes.
+        examples: ['browser.mouse.click', 'device.app.lifecycle']

internal/otelschema/_testdata/model/logs/general.yaml

@@ -0,0 +1,19 @@
+groups:
+  - id: log.record
+    prefix: log.record
+    type: attribute_group
+    brief: >
+      The attributes described in this section are rather generic. They may be used in any Log Record they apply to.
+    attributes:
+      - id: uid
+        type: string
+        requirement_level: opt_in
+        brief: >
+          A unique identifier for the Log Record.
+        note: >
+          If an id is provided, other log records with the same id will be considered duplicates and can be removed safely.
+          This means, that two distinguishable log records MUST have different values.
+
+          The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec),
+          but other identifiers (e.g. UUID) may be used as needed.
+        examples: ["01ARZ3NDEKTSV4RRFFQ69G5FAV"]

internal/otelschema/_testdata/model/logs/log-exception.yaml

@@ -0,0 +1,16 @@
+groups:
+  - id: log-exception
+    type: attribute_group
+    prefix: exception
+    brief: >
+      This document defines attributes for exceptions represented using Log
+      Records.
+    attributes:
+      - ref: exception.type
+      - ref: exception.message
+      - ref: exception.stacktrace
+
+    constraints:
+      - any_of:
+          - "exception.type"
+          - "exception.message"