-
Notifications
You must be signed in to change notification settings - Fork 33
Events
ValueStream works by subscribing to events from multiple different sources. It does this by exposing a webhook per event source.
<< INSERT DIAGRAM ON EVENT TOPOLOGY >>
ValueStream tracks events in order to measure DevOps progress, tool and process efficiency.
An event is an action. It happens at a point in time.
Events represent states of a single operation, the most important states are the start and the end state:
<< DIAGRAM OPERATION WITH START AND END STATE >>
When these states are associated through an operation. In ValueStream's data model this operation is called a Span.
A complete span is formed when both a start and an end event are received.
ValueStream supports a number of different event types:
| Type | Description |
|---|---|
| Issue | Represents work items. This is a ticket or task. It will eventually transition from Todo to a completed state. Usually represents the basic unit of work. This is critical to measure because it is the foundational unit for work across the industry. Low issue completion rates and long issue latencies are strong indicators of performance. |
| Pull Request | A unit of code to be reviewed. Code reviews are essential to measure because they are an often expensive synchronization point for multiple teams with in organization. Long code reviews can indicate expensive cross team initiatives, complicated technologies, technical debt or cultural and prioritization issues. |
| Build | Builds represent an action required to prepare code for deployment and value delivery to customers. Build tasks are commonly executed by dedicates systems and include actions like installing dependencies, linting, running tests and packaging. The rate of builds are a good indicator of how often software is being modified and iterated on. Builds with high error rates are strong indicators of technical health and builds with long latencies are a huge source of wasted engineering time. |
| Deploy | Deploys are the process of getting code into the hands of customers by taking a package and getting it running in order for customers to interact with. Build success ratio is a huge indicator of health and an organizations ability to safely ship code. Long build times are a strong indicator of technical debt and how fast an organization can deliver value to customers. |
| Pipeline | A pipeline represents an event that is composed of multiple sub events. These are things like build pipelines where a build is promoted through multiple different stages: linting, unit tests, integration tests, canarying, etc, or an issue on a kanban board that transitions from TODO to In Progress, to Done. |
Each source may support some or all of the above types. For example Github doesn't have action (build metrics) so is unable to support build and deploy metrics.
| Source | Integration | Issues | Pull Requests | Builds | Deploys | CI Pipelines | Sprint |
|---|---|---|---|---|---|---|---|
| Github | Webhooks | ✅ | ✅ | ❌ | ❌ | ❌ | ➖ |
| Jenkins | statistics-gatherer-plugin | ➖ | ➖ | ✅ | ✅ | ❌ | ➖ |
| Custom HTTP (JSON) | Tutorial | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Gitlab | Webhooks | ✅ | ✅ | ✅ | ✅ | ✅ | ➖ |
| Jira | Webhooks | Kanban | ➖ | ➖ | ➖ | ➖ | ✅ |
- GitHub Pull Requests
Each Event Source supports different types of event
| Attribute | Description | Source | Method | Ref |
|---|---|---|---|---|
| span_id | The operation that each event belongs to. ie. issue id, build id. Must be completely unique across all event sources. | client defined | SpanID() (string, error) | LINK |
| parent_span_id | (optional) The operation that causes this current operation. | client defined: value is a span_id
|
ParentSpanID() ( *string, error) | LINK |
| is_error | Is this event a "failure"? | integration specific | IsError() (bool, error) | LINK |
| state | The current action state ie start, end, intermidiary | integration specific | State() (traces.SpanState, error) | LINK |
| trace_id | (optional) How other spans can reference this span. The trace_id will be of form: vstrace-{{ EVENT_SOURCE }}-{{ SPAN_IDENTIFIER }}
|
integration specific / client defined | TraceID() (*string, error) | LINK |
| tags | Metadata about the current operation. | integration specific / client defined | Tags() (map[string]interface{}, error) | LINK |
| operation_name | A supported operation type (issue, pull_request, build, deploy). | ValueStream defined | OperationName() string | LINK |
Events are stored internally until they form a complete span or until the internal span store buffer fills.