Instrumentation tool

Suggest Edits

The Faros CI/CD Instrumentation tool helps you generate code snippets that will send events to Faros with information about your builds and deployments.

Although it’s possible to construct these code blocks yourself using the Faros Event CLI docs, creating them in Faros leverages the data you have in Faros to help fill in some of the required information.

❗️

It's possible to collect similar data through sources but this approach requires strict naming conventions and is not recommended. If you wish to explore this please contact us at [email protected]

Using the tool

  1. Find the events generator in your Faros app under Sources > Events.
  2. Complete the form
    1. Note: Data in the dropdowns is pre-populated based on the data you have in Faros. If your Faros instance doesn't yet have data representing the values you want, you can write in other values.
  3. If it exists, copy the CI payload and paste it into your CI step
  4. Copy the CD payload and paste it into your deployment step
  5. Change the environment to whatever other environments you deploy to, copy the payload, paste and repeat!

If you are just getting started refer to our instrumentation getting started and extending events docs.

Integrating with your build and deployment pipelines

  1. Select how you want to send the event. You can use Faros Events CLI from bash or Docker, or just go with a simple cURL.

  2. Paste the CI code into your system after an artifact build step. Paste the CD code into your system after a deployment step.

📘

Remember to set your variables

You'll notice each snippet has several variables defined. These values should not be hardcoded. Aside from the Faros API key, these variables are values that will be specific to each run. For example, in the CI event, the Build Started and Build End track how long the process to create the artifact took this round. It's important that if you are using both CI and CD events they use the same definition of Artifact

Where you put these code snippets is very system-dependent. The rule of thumb is to put the CI code snippet after the step where you build the artifact and the CD snippets after the step you deploy the artifact. We provide some examples below.

Examples

Sending a CI event from Bitbucket

pipelines:
  default:
    - step:
        name: Send CI Event to Faros
        script:
          - apt-get update && apt-get install -y curl jq sed gawk
          - export FAROS_API_KEY="${FAROS_API_KEY}";
          - export CI_START_TIME="$(date +%s%N | cut -b1-13)"
          - ...
          - ...
          - export CI_END_TIME="$(date +%s%N | cut -b1-13)"
          - export CI_STATUS= < Success, Failed, Canceled >
          - ...
          - export FAROS_CLI_VERSION="v0.5.0" curl -s https://raw.githubusercontent.com/faros-ai/faros-events-cli/$FAROS_CLI_VERSION/faros_event.sh | bash -s
          - >
            ./faros_event.sh CI -k "<faros_api_key>" \
            --run "<run_source>://<run_organization>/{$RUN_PIPELINE}/{$RUN_ID}" \
            --commit "<commit_source>://<commit_organization>/{$COMMIT_REPOSITORY}/{$COMMIT_SHA}" \
            --artifact "<artifact_source>://<artifact_organization>/{$ARTIFACT_REPOSITORY}/{$ARTIFACT_ID}" \
            --run_status {$CI_STATUS} \
            --run_start_time {$CI_START_TIME} \
            --run_end_time {$CI_END_TIME}

Sending CI and CD events from GitHub Actions

  1. Example using Faros Events CLI.
  2. Or use a specialized Faros CI/CD Action for GitHub from GitHub marketplace

Updated 6 months ago