Change Events

A Change Event is any change to your system — a new configuration, a feature launch, or a new type of user traffic. Most system and service outages are caused by some kind of system change, so keeping track of them, when they happened, and what components were affected can dramatically impact incident mitigation.

On FireHydrant, Change Events can be created by an integration, via our CLI tool, via API calls, and manually from the FireHydrant UI.

Adding a Change Event

Automatically via Integrations

Our GitHub and Kubernetes integrations will automatically log change events. See the linked docs pages for more information.

Via FH CLI

CLI tool

Via API

To use FireHydrant's API, you will first need to create an API key, which requires Owner permissions. From there, you can make use of the POST /changes/events endpoint.

Via User Interface

In the left nav, click Service Catalog > Change events , then click +Create event

Creating a change event

On this page, provide information related to the change event.

Summary (required) - Provide a title or quick summary of the change. This is the only required field.
Description - Markdown-enabled description field (shown in the UI such as on the Change Events tab of an incident).
Labels - Add key/value pairs that make it easier to filter and find change events. Labels are string to string pairs.
Time Range - Allows you to set either a Point in Time or Range. This is valuable if you're making an immediate change (such as changing a feature flag from off to on) as opposed to a change associated with a longer duration (such as a rolling update to a set of servers).
Services - Any services related to this change event. You can specify multiple services (or none).
Environments - Any environments related to this change event. You can specify multiple environments (or none).

After entering all of the relevant information, click Submit to create the change event.

Change Identities

Building on the above, FireHydrant enables you to loosely link change events together using what we call Change Identities - when you create change events via the FireHydrant API, you can include a key change_identities with them.

For example, you might send one change event from your continuous integration system and another from your deployment system. Each of these is a unique change event, but you can tie them together with an identity such as the commit SHA that initiated both automations.

Example Usage

Create Change Event w/ Identity

For example, your test runner can send a change event and include an identity value of commit_sha with a value of abc123 (change events can have multiple identities associated with them). When your test suite completes, using cURL, we can send a change event with the commit sha as an identity:

$ curl -X POST -H "Authorization: Bearer fhb-your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Finished Test Run",
    "starts_at": "2019-05-07T08:00:00",
    "change_identities": [
      {
        "type": "commit_sha",
        "value": "abcdef123456789"
      }
    ]
  }' https://api.firehydrant.io/v1/changes/events

This creates a change event in FireHydrant with the commit sha as an identity. change.event.sha.png
When you include an identity, a Change is also created containing all of the linked change events.

Note: The value for each type in a change identity must be unique for a given change event. Duplicate values will be silently dropped. If you have types that may reasonably contain duplicate values,authorandreviewerfor instance, consider using alabelinstead.

Linking change events using an identity

Now, let's create another change event, with the same change identity, but also include another identity for a Docker image tag.

$ curl -X POST -H "Authorization: Bearer fhb-your-token-here" \
  -H "Content-Type: application/json" \
  -d '{ 
    "summary": "Built Docker Image",
    "starts_at": "2019-05-07T08:00:00",
    "change_identities": [
      {
        "type": "commit_sha",
        "value": "abcdef123456780"
      },
      {
        "type": "image",
        "value": "registry.firehydrant.io/firehydrant/laddertruck:master-abcdef123456789"
      }
    ]
  }' https://api.firehydrant.io/v1/changes/events

The above cURL snippet creates a change event just like the previous request; however, this new change event is also automatically linked to our previous change.
All associated change events are cited (and linked) in the Associated Changes section at the bottom of the page.
associated.changes.png

Loosely linking change events using partial identity

Now, we can loosely link another change event in our deployment pipeline by only including a partial overlap of another change event's identities.

This is a valuable option, because as a change moves through a pipeline, different stages have different contexts. With a CI pipeline, you can usually get the commit sha; but for a deployment to a server, you may only know the artifact name (such as a Docker image or tarball name). By including previous identities, we can link events loosely together.

Let's create another change event with only our Docker image:

$ curl -X POST -H "Authorization: Bearer fhb-your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Deployed to Kubernetes (Production)",
    "starts_at": "2019-05-07T09:10:00",
    "change_identities": [
      {
        "type": "image",
        "value": "registry.firehydrant.io/firehydrant/laddertruck:master-abcdef123456700"
      }
    ]
  }' https://api.firehydrant.io/v1/changes/events

In this example, we're only including the "image" identity that matches the previous change event we sent. FireHydrant links this event this together to the others and includes it in your grouped change view.