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](https://github.com/coralogix-circleci/coralogix-orb)

## 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.

```text
version: 2.1
```

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

```yaml
orbs:
coralogix: coralogix/coralogix@0.7.0
```

1. Use coralogix elements in your existing workflows and jobs.
1. 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.

```yaml
jobs:
  build:
    docker:
      - image: 'cimg/base:stable'
    steps:
      - run: echo "Typical build job"
orbs:
  coralogix: coralogix/coralogix@x.y.z
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.

```yaml
jobs:
  build:
    docker:
      - image: 'cimg/base:stable'
    steps:
      - run: echo "Build the application" > build.log
      - coralogix/send:
          file: build.log
orbs:
  coralogix: coralogix/coralogix@x.y.z
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.

```yaml
jobs:
  build:
    docker:
      - image: 'cimg/base:stable'
    steps:
      - run: echo "Typical build job"
orbs:
  coralogix: coralogix/coralogix@x.y.z
version: 2.1
workflows:
  your-workflow:
    jobs:
      - build
      - coralogix/stats
```

*Sample stats log:*

```json
{"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":"noreply@gmail.com","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":"noreply@gmail.com"}],"pull_requests":[],"author_date":"2021-10-30T09:35:57.000Z","author_email":"noreply@gmail.com","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":"noreply@gmail.com","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](https://coralogix.com/tutorials/software-builds-display/)

```yaml
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/coralogix@x.y.z
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

| PARAMETER      | DESCRIPTION                                                                                                                                        | REQUIRED | DEFAULT               | TYPE         |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------- | ------------ |
| application    | Your application name                                                                                                                              | -        | CircleCI              | string       |
| category       | The log's category                                                                                                                                 | -        | logs                  | string       |
| circle-token   | Your CircleCI personal access token for interacting with the API. You can generate one here: https://circleci.com/account/api                      | -        | CIRCLE_TOKEN          | env_var_name |
| hostname       | Machine hostname.                                                                                                                                  | -        | $(hostname)           | string       |
| keep_artifacts | Keep temporary log files generated during the job after being sent to coralogix.                                                                   | -        | false                 | boolean      |
| private_key    | [Send-Your-Data API key](https://coralogix.com/docs/user-guides/account-management/api-keys/send-your-data-api-key/index.md) provided by Coralogix | -        | CORALOGIX_PRIVATE_KEY | env_var_name |
| subsystem      | Your subsystem name.                                                                                                                               | -        | workflow-stats        | string       |

## Commands

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

| PARAMETER       | DESCRIPTION                                                                                                                                        | REQUIRED | DEFAULT                 | TYPE         |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------- | ------------ |
| application     | Your application name                                                                                                                              | -        | CircleCI                | string       |
| category        | The log's category.                                                                                                                                | -        | artifact                | string       |
| class           | The log's class name.                                                                                                                              | -        | ''                      | string       |
| file            | Absolute or relative path to the file for sending.                                                                                                 | Yes      | -                       | string       |
| hostname        | Machine hostname.                                                                                                                                  | -        | $(hostname)             | string       |
| method          | The log's method name.                                                                                                                             | -        | ''                      | string       |
| newline_pattern | Regular expression to split records in the file.                                                                                                   | -        | \\n                     | \\r          |
| private_key     | [Send-Your-Data API key](https://coralogix.com/docs/user-guides/account-management/api-keys/send-your-data-api-key/index.md) provided by Coralogix | -        | CORALOGIX_PRIVATE_KEY   | env_var_name |
| subsystem       | Your subsystem name.                                                                                                                               | -        | workflow                | string       |
| thread          | Thread 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](https://coralogix.com/tutorials/software-builds-display/)

| PARAMETER   | DESCRIPTION                                                                                                                                        | REQUIRED | DEFAULT               | TYPE         |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------- | ------------ |
| application | Your application name.                                                                                                                             | Yes      | -                     | string       |
| icon        | 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.             | -        | ''                    | string       |
| private_key | [Send-Your-Data API key](https://coralogix.com/docs/user-guides/account-management/api-keys/send-your-data-api-key/index.md) provided by Coralogix | -        | CORALOGIX_PRIVATE_KEY | env_var_name |
| subsystems  | Your subsystem names. You can set more than one subsystem name by using ',' comma as a delimiter between subsystems names.                         | Yes      | -                     | string       |
| tag         | Name presented for the tag.                                                                                                                        | Yes      | -                     | string       |

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

| PARAMETER      | DESCRIPTION                                                                                                                   | REQUIRED | DEFAULT      | TYPE         |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------ |
| circle-token   | Your CircleCI personal access token for interacting with the API. You can generate one here: https://circleci.com/account/api | -        | CIRCLE_TOKEN | env_var_name |
| keep_artifacts | Keep generated workflow data.                                                                                                 | -        | false        | boolean      |

## Executors

**Default**\
Default environment for Coralogix.

| PARAMETER | DESCRIPTION       | REQUIRED | DEFAULT   | TYPE   |
| --------- | ----------------- | -------- | --------- | ------ |
| image     | Docker image name | -        | cimg/base | string |
| tag       | Docker image tag  | -        | stable    | string |

## Orb Source

```yaml
# 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://ingress.[[DOMAIN_VALUE]]' > /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.[[DOMAIN_VALUE]]/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/coralogix@x.y.z
      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/coralogix@x.y.z
      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/coralogix@x.y.z
      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/coralogix@x.y.z
      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/jq@1.9.0
version: 2.1
```

## Additional resources

|                     |                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------- |
| Coralogix Endpoints | [Coralogix Endpoints](https://coralogix.com/docs/integrations/coralogix-endpoints/index.md) |