CLI for reporting events to Faros platform.
The script provides all the necessary instrumentation for CI/CD pipelines by sending events to Faros platform
Requirements: Please make sure the following are installed before running the script - curl, jq, sed and an implementation of awk (we recommend gawk).
- Download the script manually and execute it:
$ ./faros_event.sh help- Or download it with
curland invoke it in one command:
$ export FAROS_CLI_VERSION="v0.3.2"
$ curl -s https://raw.githubusercontent.com/faros-ai/faros-events-cli/$FAROS_CLI_VERSION/faros_event.sh | bash -s helpRequirements: Docker client and runtime.
- Pull the image:
$ docker pull farosai/faros-events-cli:v0.3.2- Run it:
$ docker run farosai/faros-events-cli:v0.3.2 helpAn event type (e.g. CI, CD) corresponds to the step of your CI/CD pipeline that you are instrumenting.
- Use
CIevents to instrument code build pipelines. For example, you can report the result of a successful code build:
$ ./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 "Success" \
--run_start_time "1626804346000" \
--run_end_time "1626804358000"- Use
CDevents to instrument deployment pipelines. For example, you can report the result of a successful deployment:
$ ./faros_event.sh CD -k "<faros_api_key>" \
--artifact "<artifact_source>://<artifact_organization>/<artifact_repository>/<artifact_id>" \
--deploy "<deploy_source>://<application>/<environment>/<deploy_id>" \
--deploy_status "Success" \
--deploy_start_time "1626804356000" \
--deploy_end_time "1626804357000"Every time an artifact is deployed to an environment, you can send an event.
There are two ways that arguments can be passed into the script. The first, is via flags. The second is via environment variables. You may use a combination of these two options. If both are set, flags will take precedence over environment variables.
đź“ť Note: By convention, you can switch between using a flag or an environment variable by simply capitalizing the argument name and prefixing it with FAROS_. For example, --commit becomes FAROS_COMMIT, --artifact becomes FAROS_ARTIFACT.
| Argument | Description | Required | Default |
|---|---|---|---|
| ‑‑api_key | Your Faros API key. See the documentation for more information on obtaining an api key. | Yes | |
| ‑‑url | The Faros API url to send the event to. | https://prod.api.faros.ai |
|
| ‑‑graph | The graph that the event should be sent to. | "default" | |
| ‑‑origin | The origin of the event that is being sent to Faros. | "Faros_Script_Event" | |
| ‑‑dry_run | Print the event instead of sending. (no value accepted, true if flag is present) | False | |
| ‑‑silent | Unexceptional output will be silenced. (no value accepted, true if flag is present) | False | |
| ‑‑debug | Helpful information will be printed. (no value accepted, true if flag is present) | False | |
| ‑‑skip_saving_run | Do not include cicd_Build in the event. (no value accepted, true if flag is present) | False | |
| ‑‑no_lowercase_vcs | Do not lowercase commit_organization and commit_repo. (no value accepted, true if flag is present) | False | |
| ‑‑validate_only | Event will not be consumed but instead will only be validated against event schema. (no value accepted, true if flag is present) | False |
A CI event communicates the outcome of a code build pipeline execution, and its artifact.
You may need to scroll to the right to view the entire table.
| Argument | Description | Required | Allowed Value |
|---|---|---|---|
| ‑‑commit | The URI of the commit. (<source>://<organization>/<repository>/<commit_sha> e.g. GitHub://faros-ai/my-repo/da500aa4f54cbf8f3eb47a1dc2c136715c9197b9) |
Yes | |
| ‑‑artifact | The URI of the artifact. (<source>://<organization>/<repository>/<artifact_id> e.g. DockerHub://farosai/my-repo/da500aa4f54cbf8f3eb47a1dc2c136715c9197b9) |
||
| ‑‑run | The URI of the job run that built the code. (<source>://<organization>/<pipeline>/<run_id> e.g. Jenkins://faros-ai/my-pipeline/1234) |
||
| ‑‑run_status | The status of the job run that built the code. | If ‑‑run provided | Success, Failed, Canceled, Queued, Running, Unknown, Custom |
| ‑‑run_name | The name of the job run that built the code. | ||
| ‑‑run_status_details | Any extra details about the status of the job run. | ||
| ‑‑run_start_time | The start time of the job run in milliseconds since the epoch. (e.g. 1626804346019) |
||
| ‑‑run_end_time | The end time of the job run in milliseconds since the epoch. (e.g. 1626804346019) |
A CD event communicates the outcome of an application deployment pipeline execution, and the environment (e.g. QA, Prod).
You may need to scroll to the right to view the entire table.
| Argument | Description | Required | Allowed Value |
|---|---|---|---|
| ‑‑deploy | The URI of the deployment. (<source>://<application>/<environment>/<deploy_id> e.g. ECS://my-app/Prod/1234) |
Yes | environment: Prod, Staging, QA, Dev, Sandbox, Custom |
| ‑‑deploy_status | The status of the deployment. | Yes | Success, Failed, Canceled, Queued, Running, RolledBack, Custom |
| ‑‑artifact | The URI of the artifact. (<source>://<organization>/<repository>/<artifact_id> e.g. DockerHub://farosai/my-repo/da500aa4f54cbf8f3eb47a1dc2c136715c9197b9) |
Either ‑‑commit or ‑‑artifact | |
| ‑‑commit | The URI of the commit. (<source>://<organization>/<repository>/<commit_sha> e.g. GitHub://faros-ai/my-repo/da500aa4f54cbf8f3eb47a1dc2c136715c9197b9) |
Either ‑‑commit or ‑‑artifact | |
| ‑‑deploy_app_platform | The compute platform that runs the application. | ||
| ‑‑deploy_env_details | Any extra details about the deployment environment. | ||
| ‑‑deploy_status_details | Any extra details about the status of the deployment. | ||
| ‑‑deploy_start_time | The start time of the deployment in milliseconds since the epoch. (e.g. 1626804346019) |
||
| ‑‑deploy_end_time | The end time of the deployment in milliseconds since the epoch. (e.g. 1626804346019) |
||
| ‑‑run | The URI of the job run executing the deployment. (<source>://<organization>/<pipeline>/<run_id> e.g. Jenkins://faros-ai/my-pipeline/1234) |
||
| ‑‑run_status | The status of the job run executing the deployment. | If ‑‑run provided | Success, Failed, Canceled, Queued, Running, Unknown, Custom |
| ‑‑run_status_details | Any extra details about the status of the job run executing the deployment. | ||
| ‑‑run_start_time | The start time of the job run in milliseconds since the epoch. (e.g. 1626804346019) |
||
| ‑‑run_end_time | The end time of the job run in milliseconds since the epoch. (e.g. 1626804346019) |
The following sends an event that communicates that a deployment pipeline that is run by Buildkite which is called payments-service-deploy-prod was successful. It communicated that the application payments-service was successfully deployed with ECS to the Prod environment. It communicates that the artifact that was deployed is stored in DockerHub in the my-app-repo repository. And Finally it communicates the timestamps for the start and end of both the job run and the deployment.
$ ./faros_event.sh CD -k "<api_key>" \
--run "Buildkite://faros-ai/payments-service-deploy-prod/4206ac01-9d2f-437d-992d-8f6857b68378" \
--run_status "Success" \
--run_start_time "1626804346000" \
--run_end_time "1626804358000" \
--deploy "ECS://payments-service/Prod/d-CGAKEHE8S" \
--deploy_status "Success" \
--deploy_start_time "1626804356000" \
--deploy_end_time "1626804357000" \
--artifact "DockerHub://farosai/my-app-repo/285071b4d36c49fa699ae87345c3f4e61abba01b"We use ShellSpec to test our scripts.
brew tap shellspec/shellspec
brew install shellspecMove to the /test directory and execute shellspec
cd test && shellspec