Area(s)

area:new, area:cloudevents, area:deployment

Relates to #832 #833

Is your change request related to a problem? Please describe.

This is an issue being opened for broader discussion within the CI/CD Working Group and Semantic Conventions WG to gauge direction on the addition of conventions for CI and CD. This proposal details out at a moderately level the direction to evolve our support of CloudEvents and leverage extensions in order to define the exact attributes we support, where they come from in the community, etc.

Describe the solution you'd like

Below are an incomplete set extended attributes for subject.type for CI/CD. These attributes primarily come from v0.3.0 of CDEvents.

• taskRun # from Core Events
• pipelineRun # from Core Events
• build # from CI
• artifact # from CI
• repository # from Source Code
• branch # from Source Code
• change # from Source Code
• environment # from CD
• service # from CD
• incident # from CO
• testCaseRun # from Tests
• testSuiteRun # from Tests
• testOutput # from Tests

The CDEvents specification is broken down into multiple sections:

• core events
• source code
• continuous integration
• continuous deployment
• continous operations
• testing events
• cloudevents bindings

An example of what CDEvents bound to CloudEvents looks like can be found here and is copied below.

POST /sink HTTP/1.1
Host: cdevents.example.com
ce-specversion: 1.0
ce-type: dev.cdevents.taskrun.started.0.1-draft
ce-time: 2018-04-05T17:31:00Z
ce-id: A234-1234-1234
ce-source: /staging/tekton/
ce-subject: /namespace/taskrun-123
Content-Type: application/json; charset=utf-8
Content-Length: nnnn

{
   "context": {
      "version": "0.3.0",
      "id" : "A234-1234-1234",
      "source" : "/staging/tekton/",
      "type" : "dev.cdevents.taskrun.started",
      "timestamp" : "2018-04-05T17:31:00Z",
   }
   "subject" : {
      "id": "/namespace/taskrun-123",
      "type": "taskRun",
      "content": {
         "task": "my-task",
         "url": "/apis/tekton.dev/v1beta1/namespaces/default/taskruns/my-taskrun-123"
         "pipelineRun": {
            "id": "/somewherelse/pipelinerun-123",
            "source": "/staging/jenkins/"
         }
      }
   }
}

Each one of these subjects, would be associated with a predicate which is what happens to the subject in an occurrence. For example, taskRun would be followed by started. This does need more conversation around timestamps. Based on one of the WG, one of the key questions was surrounding start & stop times. Because of the nature of event predicates in CDEvents and the event definitions for Eiffel, events denote what type they are (ie. start / finished) and have corresponding timestamps the event was created. Due to the nature of distributed tracing with regards to the CloudEvents specification, this shouldn't conflict with the current tracing specification.

An example event workflow within a CI system may look like this:

The example CI system above would send event data over OTLP with the attribute examples listed above.
I've leaned towards these attributes for these reasons:

• CDEvents extends CloudEvents through data bindings.
• CloudEvents is supported within OpenTelemetry as experimental and offers
• CDEvents and CloudEvents have CDFoundation Support

Describe alternatives you've considered

Eiffel could be made to extend CloudEvents just like CDEvents, which would enable choice selection and interoperability between conventions. Trace propagation will occur then as per the CloudEvents spec defined in opentelemetry with the addition of attributes aligning with CI/CD.

Additional context

The one currently identified divergence between CloudEvents Distributed Tracing and CI/CD systems in the method of propagation. This is for the traceparent, which can be propagated within CI/CD systems to provide inter-process context propagation. Environment carries as context and baggage propagators is going to be key for batch systems like CI to be able to emit events with correct lineage.

Current outstanding thoughts and concerns:

• use of predicates for start / stop and it's relation to the OTEL span / trace standard.
• choosing one specification over the other, excluding a potential portion of the user base
  • this could be solved by Eiffel becoming an extension of CloudEvents similar to CDEvents -> CloudEvents bindings.
• When supporting CDEvents, certain attributes from CloudEvents that were previously optional, MUST be set as part of the extension.
• CloudEvents distributed tracing defines HTTP & Binary standards only.
• Context propagation through environment variable propagators isn't specification, yet.
• Current specifications are experimental, new, and not all encompassing.