With all the possibilities that instrumentation supports, getting started can be a little daunting. This doc walks you through how to approach sending these events.

Getting started with Production deployments

The best place to start for instrumenting your CI/CD pipelines is to focus on production deployments.

Writing production deployment information to Faros will let you see insights like lead time. Dashboards like those found in the Value Stream Module will begin displaying data with just production deployment events.

Once you have successfully instrumented these, you can get more granular insights.

📘

Before continuing, make sure you have a VCS (Version Control Software) source setup in your graph that is pulling repository and commit data.

Required information

To instrument these production deployments you’ll need to know

• When did the deployment happen?
  • Start time, End time
• What was its status?
• What was deployed?
  • Which commit?
  • Which application?
• How can we track this deployment
  • Id (this needs to be unique across all of your deployments)

Constructing the event

Use the Faros CI/CD Instrumentation tool, found in the Faros app, to easily construct the event.

With the tool you’ll be able to create a code snippet that uses the data you have in Faros to help fill in some of the needed information.

Remember, for starting out we are focusing on only instrumenting production deployments. Make sure that in the form you:

1. Select the option for tracking only deployments
2. Set the environment to prod!

Once you’ve constructed the snippet you can choose how you want to send the snippet: You can use Faros Events CLI from bash or Docker, or just go with a simple cURL.

❔

What if I don’t have the commit sha in the context of my deployment?

Some pipelines deploy artifacts instead of directly deploying commits. If your company uses artifacts you will need to instrument both the artifact creation (CI) and the artifact deployment (CD) see these docs for more details.

Adding the code to your pipelines

Now that you have a snippet, you just need to figure out what should execute it. The instrumentation will need to be in a place that has the context for all of the deployment details listed above (these are found as the variables in the snippet).

If there are multiple places that meet this requirement, put the instrumentation in a place that covers the most apps. This saves you work!

❔

What if I want to use the same snippet for multiple apps?

That’s great! We actually recommend that you find a place to put a single snippet that can be executed for all apps. You’ll need to modify the snippet slightly to extract the application name and make it a variable like the deploy ID. You’ll find it in the -–deploy option as the first argument in the URI, right before /PROD/

What is the build/deploy URI and how do I construct it?

A URI is a way to send multiple pieces of information in a single line. This keeps your code clean by reducing the number of lines in the snippet. In a URI, multiple values are sent in a single field, their values separated by slashes. For example the deploy URI --deploy <DEPLOYMENT_SYSTEM>://<APP>/Prod/$DEPLOY_ID contains all of the information about the deployment object in a single field.

To construct the URIs it’s easiest to use our CI/CD Instrumentation tool. Feel free to extract any values out to variables.

It’s also possible to send each value as its own field. The benefit of this approach is improved readability. If you’d like to send events in this form it’s easy to switch over. Check out these docs for information on each field.

Verify your instrumentation

You can verify that your deployments are being written to Faros and check that they are correctly tied to commits. Check out the troubleshooting page for details.

Where to go from here

From here it is all about increasing granularity; this can be done in two ways.

1. If you deploy to other environments you can instrument those deployments in the same way that you instrumented prod.
2. If you are interested in build data refer to this doc that dives into sending CI events.