Skip to content

CircleCI

Integrate your CircleCI workflows and jobs pipeline with Coralogix to automatically receive reports and analyze version upgrades for their impact on the overall quality of your production system.

Coralogix Orb provides four tools:
coralogix/stats (job) - send the final report of a workflow job to Coralogix.
coralogix/logs (job) - send logs of workflow jobs to Coralogix for debugging.
coralogix/send (command) - send additional 3rd party logs generated during your workflow job to Coralogix.
coralogix/tag (command) - create a tag (and a report) for the workflow in Coralogix.

GitHub Repository

Getting Started

1. Use CircleCI version 2.1 at the top of your .circleci/config.yml file. If you do not already have Pipelines enabled, you'll need to go to Project Settings -> Advanced Settings and turn it on.

version: 2.1

2. Add the orbs stanza below your version, invoking the orb:

orbs:
coralogix: coralogix/[email protected]

3. Use coralogix elements in your existing workflows and jobs.

4. Opt-in to use of third-party orbs on your organization’s Security settings page.

Usage Examples

Logs
This example shows how you can debug a workflow job in Coralogix. By adding our Orb and the coralogix/logs job at the end of the flow, you'll receive all logs CircleCI generates during the workflow in your Coralogix account, helping you debug the different jobs.

Note that this may generate a large amount of data, and is recommended for debugging purposes only.

jobs:
  build:
    docker:
      - image: 'cimg/base:stable'
    steps:
      - run: echo "Typical build job"
orbs:
  coralogix: coralogix/[email protected]
version: 2.1
workflows:
  your-workflow:
    jobs:
      - build
      - coralogix/logs

Send
This example shows how you can send additional 3rd party logs generated during your workflow job to Coralogix.
By adding our Orb and the coralogix/send step, you can send additional logs from an external file to your Coralogix account.
This is especially useful if one of the stages of your job generates an external file with logs which you'd like to report to Coralogix and analyze along with the rest of your logs.

jobs:
  build:
    docker:
      - image: 'cimg/base:stable'
    steps:
      - run: echo "Build the application" > build.log
      - coralogix/send:
          file: build.log
orbs:
  coralogix: coralogix/[email protected]
version: 2.1
workflows:
  your-workflow:
    jobs:
      - build

Stats
This example shows how you can send the final report of a workflow job to Coralogix.
By adding our Orb and the coralogix/stats job at the end of the flow, you'll receive the report automatically in your Coralogix account and can analyze and aggregate the results.

jobs:
  build:
    docker:
      - image: 'cimg/base:stable'
    steps:
      - run: echo "Typical build job"
orbs:
  coralogix: coralogix/[email protected]
version: 2.1
workflows:
  your-workflow:
    jobs:
      - build
      - coralogix/stats

Sample stats log:

{"timedout":false,"subject":"circle-ci: stats","vcs_url":"https:\/\/github.com\/testUser\/coralogix-orb","owners":["testUser"],"body":"","branch":"main","oss":true,"canceler":null,"lifecycle":"finished","all_commit_details":[{"committer_date":"2021-10-30T09:35:57.000Z","body":"","branch":"main","author_date":"2021-10-30T09:35:57.000Z","committer_email":"[email protected]","commit":"efd612f70c05f4c99b1eb1c053932b601c1bdce6","committer_login":"testUser","committer_name":"testUser","subject":"circle-ci: stats","commit_url":"https:\/\/github.com\/testUser\/coralogix-orb\/commit\/efd612f70c05f4c99b1eb1c053932b601c1bdce6","author_login":"testUser","author_name":"testUser","author_email":"[email protected]"}],"pull_requests":[],"author_date":"2021-10-30T09:35:57.000Z","author_email":"[email protected]","build_url":"https:\/\/circleci.com\/gh\/testUser\/coralogix-orb\/5","picard":{"build_agent":{"image":"1.0.88908-3b88b179","properties":{"executor":"docker","nomad_ami":"ami-0c36d9771f57f278d","availability_zone":"us-east-1a","instance_id":"i-0bec297a27096bcbc","instance_ip":"172.29.97.200","build_agent":"1.0.88908-3b88b179"}},"executor":"docker","resource_class":{"cpu":2,"ram":4096,"class":"medium","name":"Docker Medium"}},"all_commit_details_truncated":false,"ssh_users":[],"queued_at":"2021-10-30T09:36:17.061Z","build_time_millis":2143,"is_first_green_build":false,"previous_successful_build":{"build_num":3,"status":"success","build_time_millis":2599},"failed":false,"infrastructure_fail":false,"build_parameters":{},"committer_name":"testUser","start_time":"2021-10-30T09:36:19.276Z","retries":null,"canceled":false,"node":null,"build_num":5,"messages":[],"ssh_disabled":true,"fail_reason":null,"usage_queued_at":"2021-10-30T09:36:16.972Z","vcs_revision":"efd612f70c05f4c99b1eb1c053932b601c1bdce6","status":"success","author_name":"testUser","retry_of":null,"compare":null,"stop_time":"2021-10-30T09:36:21.419Z","why":"github","committer_date":"2021-10-30T09:35:57.000Z","context_ids":[],"workflows":{"job_name":"build","job_id":"c66f402a-1cd0-4263-959d-a597c76a25e2","workflow_id":"c82bc001-f055-4349-a455-10e2989133c7","workspace_id":"c82bc001-f055-4349-a455-10e2989133c7","upstream_job_ids":[],"upstream_concurrency_map":{},"workflow_name":"stats-workflow"},"platform":"2.0","vcs_tag":null,"parallel":1,"outcome":"success","committer_email":"[email protected]","previous":{"build_num":4,"status":"running","build_time_millis":7042},"dont_build":null,"vcs_type":"github","job_name":null,"reponame":"coralogix-orb","has_artifacts":true,"user":{"is_user":true,"login":"testUser","avatar_url":"https:\/\/avatars.githubusercontent.com\/u\/3061368?v=4","name":null,"vcs_type":"github","id":3061368},"username":"testUser"}

Tag
This example shows how you can create a tag (and a report) for the workflow in Coralogix.
By adding our Orb and the coralogix/tag step, you can create tag (and a report) for this workflow in your Coralogix account to understand what effect it has on your production.
Learn more about tags

jobs:
  build:
    docker:
      - image: 'cimg/base:stable'
    steps:
      - run: echo "Build the application"
  deploy:
    docker:
      - image: 'cimg/base:stable'
    steps:
      - run: echo "Deploy the application"
      - coralogix/tag:
          application: MyApp
          subsystems: 'frontend,backend'
          tag: v1.0.0
  test:
    docker:
      - image: 'cimg/base:stable'
    steps:
      - run: echo "Test the application"
orbs:
  coralogix: coralogix/[email protected]
version: 2.1
workflows:
  your-workflow:
    jobs:
      - build
      - test:
          requires:
            - build
      - deploy:
          requires:
            - test

Jobs

Logs
This job is used to debug CircleCI workflow jobs in Coralogix by sending all the debug logs.
Note that this may generate a large amount of data, and is recommended for debugging purposes only.

Show Job Source

PARAMETERDESCRIPTIONREQUIREDDEFAULTTYPE
applicationYour application name-CircleCIstring
categoryThe log's category-logsstring
circle-tokenYour CircleCI personal access token for interacting with the API. You can generate one here: https://circleci.com/account/api-CIRCLE_TOKENenv_var_name
hostnameMachine hostname.-$(hostname)string
keep_artifactsKeep temporary log files generated during the job after being sent to coralogix.-falseboolean
private_keySend-Your-Data API key provided by Coralogix-CORALOGIX_PRIVATE_KEYenv_var_name
subsystemYour subsystem name.-workflow-statsstring

Commands

Send
This command is used to send additional 3rd party logs generated during your workflow job to Coralogix.

PARAMETERDESCRIPTIONREQUIREDDEFAULTTYPE
applicationYour application name-CircleCIstring
categoryThe log's category.-artifactstring
classThe log's class name.-''string
fileAbsolute or relative path to the file for sending.Yes-string
hostnameMachine hostname.-$(hostname)string
methodThe log's method name.-''string
newline_patternRegular expression to split records in the file.-\n\r
private_keySend-Your-Data API key provided by Coralogix-CORALOGIX_PRIVATE_KEYenv_var_name
subsystemYour subsystem name.-workflowstring
threadThread ID reported with the log.-'${CIRCLE_WORKFLOW_ID}'string

Tag
This command is used to create a tag (and a report) for the workflow in Coralogix, helping you understand what effect it has on your production.
Learn more about tags

PARAMETERDESCRIPTIONREQUIREDDEFAULTTYPE
applicationYour application name.Yes-string
iconA custom image to use for your tag. URL should point to a valid image file that is publicly available (png, jpeg, SVG). Max size 50KB.-''string
private_keySend-Your-Data API key provided by Coralogix-CORALOGIX_PRIVATE_KEYenv_var_name
subsystemsYour subsystem names. You can set more than one subsystem name by using ',' comma as a delimiter between subsystems names.Yes-string
tagName presented for the tag.Yes-string

Workflow
Defines the command to help ship workflow logs to Coralogix.

PARAMETERDESCRIPTIONREQUIREDDEFAULTTYPE
circle-tokenYour CircleCI personal access token for interacting with the API. You can generate one here: https://circleci.com/account/api-CIRCLE_TOKENenv_var_name
keep_artifactsKeep generated workflow data.-falseboolean

Executors

Default
Default environment for Coralogix.

PARAMETERDESCRIPTIONREQUIREDDEFAULTTYPE
imageDocker image name-cimg/basestring
tagDocker image tag-stablestring

Orb Source

# This code is licensed from CircleCI to the user under the MIT license. See
# https://circleci.com/orbs/registry/licensing for details.
commands:
  send:
    description: |
      This command is used to send additional 3rd party logs generated during your workflow job to Coralogix.
    parameters:
      application:
        default: CircleCI
        description: Your application name.
        type: string
      category:
        default: artifact
        description: The log's category.
        type: string
      class:
        default: ""
        description: The log's class name.
        type: string
      file:
        description: Absolute or relative path to the file for sending.
        type: string
      hostname:
        default: $(hostname)
        description: Machine hostname.
        type: string
      method:
        default: ""
        description: The log's method name.
        type: string
      newline_pattern:
        default: \n|\r|\r\n
        description: Regular expression to split records in the file.
        type: string
      private_key:
        default: CORALOGIX_PRIVATE_KEY
        description: Private key provided by Coralogix
        type: env_var_name
      subsystem:
        default: workflow
        description: Your subsystem name.
        type: string
      thread:
        default: ${CIRCLE_WORKFLOW_ID}
        description: Thread ID reported with the log.
        type: string
    steps:
    - jq/install
    - run:
        command: |
          if [ ! -f "<>" ]; then
              echo "File not found!"
              exit 0
          fi
          LOG_FILE=$(realpath "<>")
          LOG_BULKS=$(mktemp -d)
          pushd $LOG_BULKS
            split -C 2M -d "$LOG_FILE" ''
          popd
          for bulk in $LOG_BULKS/*; do
            LOG_BULK=$(jq -nMc \
              --rawfile lines "$bulk" \
              --arg private_key "${<>}" \
              --arg application "<>" \
              --arg subsystem "<>" \
              --arg hostname "<>" \
              --arg category "<>" \
              --arg class "<>" \
              --arg method "<>" \
              --arg thread "<>" '{
              "privateKey": $private_key,
              "applicationName": $application,
              "subsystemName": $subsystem,
              "computerName": $hostname,
              "logEntries": [
                $lines | split("<>"; "") | to_entries | .[] | {
                  "timestamp": (now * 1000 + .key),
                  "severity": 3,
                  "text": .value | select(.!=""),
                  "category": $category,
                  "className": $class,
                  "methodName": $method,
                  "threadId": $thread
                }
              ]
            }')
            curl -X POST -H 'Content-Type: application/json' -d "$LOG_BULK" -s 'https://api.coralogix.com/api/v1/logs' > /dev/null
          done
          rm -rf "$LOG_BULKS"
        name: Send to Coralogix
        when: always
  tag:
    description: |
      This command is used to create a tag (and a report) for the workflow in Coralogix, helping you understand what effect it has on your production.
      Learn more at https://coralogix.com/tutorials/software-builds-display/
    parameters:
      application:
        description: Your application name.
        type: string
      icon:
        default: ""
        description: |
          A custom image to use for your tag.
          URL should point to a valid image file that is publicly available (png, jpeg, SVG).
          Max size 50KB.
        type: string
      private_key:
        default: CORALOGIX_PRIVATE_KEY
        description: Private key provided by Coralogix
        type: env_var_name
      subsystems:
        description: |
          Your subsystem names.
          You can set more than one subsystem name by using ',' comma as a delimiter between subsystems names.
        type: string
      tag:
        description: Name presented for the tag.
        type: string
    steps:
    - run:
        command: |
          curl "https://api.coralogix.com/api/v1/addTag?key=${<>}&application=<>&subsystem=<>&name=<>&iconUrl=<>"
        name: Push Coralogix Tag
  workflow:
    description: |
      Defines the command to help ship workflow logs to Coralogix.
    parameters:
      circle-token:
        default: CIRCLE_TOKEN
        description: |
          Your CircleCI personal access token for interacting with the API.
          You can generate one here: https://circleci.com/account/api
        type: env_var_name
      keep_artifacts:
        default: false
        description: Keep generated workflow data.
        type: boolean
    steps:
    - run:
        command: |
          WORKFLOW=$(curl -s -H "Circle-Token: ${<>}" "https://circleci.com/api/v2/workflow/$CIRCLE_WORKFLOW_ID")
          WORKFLOW_JOBS=$(curl -s -H "Circle-Token: ${<>}" "https://circleci.com/api/v2/workflow/$CIRCLE_WORKFLOW_ID/jobs" | jq '.items')
          WORKFLOW_LENGTH=$(echo "$WORKFLOW_JOBS" | jq 'length')
          PROJECT_SLUG=$(echo "$WORKFLOW" | jq -r '.project_slug')

          mkdir -p /tmp/coralogix
          rm -f /tmp/coralogix/workflow-*.log
          for (( i=0; i<$WORKFLOW_LENGTH; )); do
              WORKFLOW_JOBS=$(curl -s -H "Circle-Token: ${<>}" "https://circleci.com/api/v2/workflow/$CIRCLE_WORKFLOW_ID/jobs" | jq '.items')
              JOB_NUMBER=$(echo "$WORKFLOW_JOBS" | jq -r "sort_by(.job_number) | .[$i].job_number")
              JOB_STATUS=$(echo "$WORKFLOW_JOBS" | jq -r "sort_by(.job_number) | .[$i].status")
              JOB_NAME=$(echo "$WORKFLOW_JOBS" | jq -r "sort_by(.job_number) | .[$i].name")
              if [[ $JOB_NAME != coralogix/* ]]; then
                  if [ "$JOB_STATUS" != "running" ] && [ "$JOB_STATUS" != "blocked" ]; then
                      echo "Collecting data for job $JOB_NAME..."
                      JOB=$(curl -s -H "Circle-Token: ${<>}" "https://circleci.com/api/v1.1/project/$PROJECT_SLUG/$JOB_NUMBER")
                      JOB_LOGS=$(echo "$JOB" | jq '.steps[].actions[].output_url | select(.!=null)')
                      if [ -z "$JOB_LOGS" ]; then
                          sleep 10
                          continue
                      fi
                      echo "$JOB" | jq -c 'del(.steps, .circle_yml)' >> /tmp/coralogix/workflow-stats.log
                      echo "$JOB_LOGS" | xargs -n1 curl -s --output - --compressed | jq -r '.[].message' >> /tmp/coralogix/workflow-logs.log
                      i="$((i+1))"
                  else
                      echo "Job $JOB_NAME is $JOB_STATUS..."
                      sleep 10
                  fi
              else
                  i="$((i+1))"
              fi
          done
        name: Build workflow data
        when: always
    - when:
        condition: <>
        steps:
        - store_artifacts:
            path: /tmp/coralogix
description: |
  Integrate your CircleCI workflows and jobs pipeline with Coralogix to automatically receive reports and analyze version upgrades for their impact on the overall quality of your production system.
  Coralogix Orb provides four tools at your disposal:
    coralogix/stats (job) - send the final report of a workflow job to Coralogix.
    coralogix/logs (job) - send logs of workflow jobs to Coralogix for debugging.
    coralogix/send (command) - send additional 3rd party logs generated during your workflow job to Coralogix.
    coralogix/tag (command) - create a tag (and a report) for the workflow in Coralogix.
  Website: http:/www.coralogix.com
  Learn more: https://coralogix.com/category/tutorials/
  Repository: https://github.com/coralogix-circleci/coralogix-orb
examples:
  logs:
    description: |
      This example shows how you can debug a workflow job in Coralogix. By adding our Orb and the coralogix/logs job at the end of the flow, you'll receive all logs CircleCI generates during the workflow in your Coralogix account, helping you debug the different jobs.
      Note that this may generate a large amount of data, and is recommended for debugging purposes only.
    usage:
      jobs:
        build:
          docker:
          - image: cimg/base:stable
          steps:
          - run: echo "Typical build job"
      orbs:
        coralogix: coralogix/[email protected]
      version: 2.1
      workflows:
        your-workflow:
          jobs:
          - build
          - coralogix/logs
  send:
    description: |
      This example shows how you can send additional 3rd party logs generated during your workflow job to Coralogix.
      By adding our Orb and the coralogix/send step, you can send additional logs from an external file to your Coralogix account.
      This is especially useful if one of the stages of your job generates an external file with logs which you'd like to report to Coralogix and analyze along with the rest of your logs.
    usage:
      jobs:
        build:
          docker:
          - image: cimg/base:stable
          steps:
          - run: echo "Build the application" > build.log
          - coralogix/send:
              file: build.log
      orbs:
        coralogix: coralogix/[email protected]
      version: 2.1
      workflows:
        your-workflow:
          jobs:
          - build
  stats:
    description: |
      This example shows how you can send the final report of a workflow job to Coralogix.
      By adding our Orb and the coralogix/stats job at the end of the flow, you'll receive the report automatically in your Coralogix account and can analyze and aggregate the results.
    usage:
      jobs:
        build:
          docker:
          - image: cimg/base:stable
          steps:
          - run: echo "Typical build job"
      orbs:
        coralogix: coralogix/[email protected]
      version: 2.1
      workflows:
        your-workflow:
          jobs:
          - build
          - coralogix/stats
  tag:
    description: |
      This example shows how you can create a tag (and a report) for the workflow in Coralogix.
      By adding our Orb and the coralogix/tag step, you can create tag (and a report) for this workflow in your Coralogix account to understand what effect it has on your production.
      Learn more at https://coralogix.com/tutorials/software-builds-display/
    usage:
      jobs:
        build:
          docker:
          - image: cimg/base:stable
          steps:
          - run: echo "Build the application"
        deploy:
          docker:
          - image: cimg/base:stable
          steps:
          - run: echo "Deploy the application"
          - coralogix/tag:
              application: MyApp
              subsystems: frontend,backend
              tag: v1.0.0
        test:
          docker:
          - image: cimg/base:stable
          steps:
          - run: echo "Test the application"
      orbs:
        coralogix: coralogix/[email protected]
      version: 2.1
      workflows:
        your-workflow:
          jobs:
          - build
          - test:
              requires:
              - build
          - deploy:
              requires:
              - test
executors:
  default:
    description: |
      Default environment for Coralogix.
    docker:
    - image: <>:<>
    parameters:
      image:
        default: cimg/base
        description: Docker image name
        type: string
      tag:
        default: stable
        description: Docker image tag
        type: string
    resource_class: small
jobs:
  logs:
    description: |
      This job is used to debug CircleCI workflow jobs in Coralogix by sending all the debug logs.
      Note that this may generate a large amount of data, and is recommended for debugging purposes only.
    executor: default
    parameters:
      application:
        default: CircleCI
        description: Your application name.
        type: string
      category:
        default: logs
        description: The log's category.
        type: string
      circle-token:
        default: CIRCLE_TOKEN
        description: |
          Your CircleCI personal access token for interacting with the API.
          You can generate one here: https://circleci.com/account/api
        type: env_var_name
      hostname:
        default: $(hostname)
        description: Machine hostname.
        type: string
      keep_artifacts:
        default: false
        description: Keep temporary log files generated during the job after being
          sent to coralogix.
        type: boolean
      private_key:
        default: CORALOGIX_PRIVATE_KEY
        description: Private key provided by Coralogix
        type: env_var_name
      subsystem:
        default: workflow-logs
        description: Your subsystem name.
        type: string
    steps:
    - workflow:
        circle-token: <>
        keep_artifacts: <>
    - send:
        application: <>
        category: <>
        file: /tmp/coralogix/workflow-logs.log
        hostname: <>
        private_key: <>
        subsystem: <>
  stats:
    description: |
      This job is used to get the final report of a workflow job in Coralogix where you can analyze a and aggregate the results.
    executor: default
    parameters:
      application:
        default: CircleCI
        description: Your application name.
        type: string
      category:
        default: logs
        description: The log's category.
        type: string
      circle-token:
        default: CIRCLE_TOKEN
        description: |
          Your CircleCI personal access token for interacting with the API.
          You can generate one here: https://circleci.com/account/api
        type: env_var_name
      hostname:
        default: $(hostname)
        description: Machine hostname.
        type: string
      keep_artifacts:
        default: false
        description: Keep temporary log files generated during the job after being
          sent to coralogix.
        type: boolean
      private_key:
        default: CORALOGIX_PRIVATE_KEY
        description: Private key provided by Coralogix
        type: env_var_name
      subsystem:
        default: workflow-stats
        description: Your subsystem name.
        type: string
    steps:
    - workflow:
        circle-token: <>
        keep_artifacts: <>
    - send:
        application: <>
        category: <>
        file: /tmp/coralogix/workflow-stats.log
        hostname: <>
        private_key: <>
        subsystem: <>
orbs:
  jq: circleci/[email protected]
version: 2.1