CLI for reporting events to Faros platform.
The script provides all the necessary instrumentation for CI/CD pipelines by sending events to Faros platform
Please make sure the following are installed before running the script:
- curl
- jq
You can download and execute the script:
$ ./faros_event.sh helpOr with curl:
# set to the latest version - https://github.com/faros-ai/faros-events-cli/releases/latest
$ export FAROS_CLI_VERSION="v0.2.0"
$ curl -s https://raw.githubusercontent.com/faros-ai/faros-events-cli/$FAROS_CLI_VERSION/faros_event.sh | bash -s 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 "<cicd_source>://<cicd_organization>/<cicd_pipeline>/<run_uid>" \
--commit "<vcs_source>://<vcs_organization>/<vcs_repo>/<commit_sha>" \
--artifact "<artifact_source>://<artifact_org>/<artifact_repo>/<artifact_uid>" \
--run_status Success- 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_org>/<artifact_repo>/<artifact_uid>" \
--deploy "<deploy_source>://<app_name>/<environment>/<deploy_uid>" \
--deploy_status SuccessThere 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 |
A CI event communicates the outcome of a code build pipeline execution, and its artifact.
| Argument | Description | Required | Default | Allowed Value |
|---|---|---|---|---|
| ‑‑commit | The URI of the commit. (<vcs_source>://<vcs_organization>/<vcs_repo>/<commit_sha> e.g. GitHub://faros-ai/my-repo/da500aa4f54cbf8f3eb47a1dc2c136715c9197b9) |
Yes | ||
| ‑‑artifact | The URI of the artifact. (<artifact_source>://<artifact_organization>/<artifact_repo>/<artifact_id> e.g. DockerHub://farosai/my-repo/da500aa4f54cbf8f3eb47a1dc2c136715c9197b9) |
|||
| ‑‑run | The URI of the job run that built the code. (<ci_source>://<ci_organization>/<ci_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) |
Now | ||
| ‑‑run_end_time | The end time of the job run in milliseconds since the epoch. (e.g. 1626804346019) |
Now |
A CD event communicates the outcome of an application deployment pipeline execution, and the environment (e.g. QA, Prod).
| Argument | Description | Required | Default | Allowed Value |
|---|---|---|---|---|
| ‑‑deploy | The URI of the deployment. (<deploy_source>://<application>/<deploy_env>/<deploy_id> e.g. ECS://my-app/Prod/1234) |
Yes | deploy_env: 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. (<artifact_source>://<artifact_organization>/<artifact_repo>/<artifact_id> e.g. DockerHub://farosai/my-repo/da500aa4f54cbf8f3eb47a1dc2c136715c9197b9) |
Either ‑‑commit or ‑‑artifact | ||
| ‑‑commit | The URI of the commit. (<vcs_source>://<vcs_organization>/<vcs_repo>/<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) |
Now | ||
| ‑‑deploy_end_time | The end time of the deployment in milliseconds since the epoch. (e.g. 1626804346019) |
Now | ||
| ‑‑run | The URI of the job run executing the deployment. (<ci_source>://<ci_organization>/<ci_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_name | The name of the job run executing the deployment. | "" | ||
| ‑‑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) |
Now | ||
| ‑‑run_end_time | The end time of the job run in milliseconds since the epoch. (e.g. 1626804346019) |
Now |
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