The Coralogix Jenkins plugin facilitates the transmission of audit, security, and pipeline console logs to Coralogix, while pushing tags to the Coralogix platform.\
**Notes:**

- To send metrics to Coralogix, use our [Jenkins Telemetry (Otel) integration](https://coralogix.com/docs/integrations/ci/cd/jenkins-telemetry/index.md).
- The Coralogix plugin will work on Jenkins version 2.277.2 and above. If your Jenkins isn't in the mentioned versions, you may try our Curl commands located further in the doc.

## Installation

- Download the `hpi` file from [GitHub releases](https://github.com/coralogix/jenkins-coralogix-plugin/releases)
- Put the `hpi` file in the directory `$JENKINS_HOME/plugins`
- Restart Jenkins

## Configuration

Go to `Manage Jenkins`, open `Configure system`, find the `Coralogix` section and configure your account [Send-Your-Data API key](https://coralogix.com/docs/user-guides/account-management/api-keys/send-your-data-api-key/index.md) for sending system/audit/security logs.

You can configure as many keys as you want.

**Notes**:

- **Send system logs** won't be checked, as it's not currently supported.
- If you use Private Link, you can change `Coralogix Region` to *Custom* and overwrite it in `Custom Coralogix endpoint` field. An example of a Custom Coralogix endpoint is `private.coralogix.com`.
- If your Coralogix [domain](https://coralogix.com/docs/user-guides/account-management/account-settings/coralogix-domain/index.md) ends with a suffix other than '.com', overwrite the `Coralogix API endpoint` value by going to the `Advanced` section and inserting:

```text
https://[[DOMAIN_VALUE]]
```

## Credentials

Before usage, create Jenkins credentials with your Coralogix [Send-Your-Data API key](https://coralogix.com/docs/user-guides/account-management/api-keys/send-your-data-api-key/index.md) for your team. Navigate to  **Manage Jenkins > Manage Credentials** and click on Jenkins under **Stores scoped to Jenkins**.

To use this API you also need to [create](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys/index.md) a personal or team API key. It’s recommended to use permission presets, as they are automatically updated with all relevant permissions. Alternatively, you can manually add individual permissions.

| Preset          | Action                                                                                          | Description                                                                              |
| --------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| CICDIntegration | `VERSION-BENCHMARK-TAGS:READ` `VERSION-BENCHMARKS-REPORTS:READ` `VERSION-BENCHMARK-TAGS:UPDATE` | View Version Benchmark Tags View Version Benchmark Reports Modify Version Benchmark Tags |

Insert the API key into the Coralogix API key field. This will allow us to use the "push tags" function since it will allow the creation of a tag each time there is a build in the pipe.

To push Tags, go under your config and click **Add build step**.

Select Push Tags to Coralogix and select the Tags key from your credentials.

## Usage

This plugin supports sending build logs and tags for Freestyle project and Pipelines.

### Send logs

Send your build logs to Coralogix.

**Freestyle project**\
Check **Send build logs to Coralogix**, select Private Key, and provide the Application and Subsystem names.

### Pipeline

This is the Groovy implementation:

```groovy
pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                echo "Hello world!"
            }
        }
    }
    post {
        always {
            coralogixSend privateKeyCredentialId: 'coralogix-production',
                          application: 'MyApp',
                          subsystem: "${env.JOB_NAME}",
                          splitLogs: true
        }
    }
}
```

### Curl

It's possible to use Curl command to create a log. Choose the https://api.\[[DOMAIN_VALUE]\]/api/v1/external/tags endpoint that corresponds to your Coralogix [domain](https://coralogix.com/docs/user-guides/account-management/account-settings/coralogix-domain/index.md) using the domain selector at the top of the page.

```bash
curl --location --request POST 'https://api.[[DOMAIN_VALUE]]/api/v1/external/tags' \
--header 'private_key: <privatekey>' \
--header 'Content-Type: application/json' \
--data-raw '{"applicationName": "prd", "subsystemName": "app", "text": "hello world", "severity": "3"}'
```

Note

"text", "severity" are optional fields.

### Push tag

Push version tag to Coralogix.

**Freestyle project**\
Add build step Push Coralogix tag and configure:

- **Private Key** - your Coralogix account [Send-Your-Data API key](https://coralogix.com/docs/user-guides/account-management/api-keys/send-your-data-api-key/index.md)
- **Tag name** - version tag name
- **Application name** - your application name
- **Subsystem names** - your subsystem names
- **Icon(optional)** - your own tag picture

### Pipeline

This is the `Groovy` representation of `Push Coralogix tag` build step:

```groovy
pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                echo "Hello world!"
            }
        }
    }
    post {
        success {
            coralogixTag apiKeyCredentialId: 'coralogix-production-api',
                         tag: '1.0.0',
                         applications: [
                            [name: 'MyApp']
                         ],
                         subsystems: [
                            [name: 'staging'],
                            [name: 'production']
                         ],
                         icon: 'https://raw.githubusercontent.com/coralogix/jenkins-coralogix-plugin/master/docs/images/logo.svg'
        }
    }
}
```

### Curl

It's possible to use Curl command to create a tag, choose the right Endpoint, add the "APIkey" and run the command below.

Note

"timestamp" and "iconUrl" are optional fields.

Choose the https://api.\[[DOMAIN_VALUE]\]/api/v1/external/tags endpoint that corresponds to your Coralogix [domain](https://coralogix.com/docs/user-guides/account-management/account-settings/coralogix-domain/index.md) using the domain selector at the top of the page.

```bash
curl --location --request POST 'https://api.[[DOMAIN_VALUE]]/api/v1/external/tags' \
--header 'Authorization: Bearer <APIKey>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "test tag",
"timestamp": <currentTimeinMilliseconds>
"application": ["prd", "dev"],
"subsystem": ["app", "mobile"],
"iconUrl": "<iconUrl>"
}'
```

## Upgrading

If upgrading from version \<= 1.17, you will get an error in the Manage Jenkins UI:

To clear this error, simply click "Manage" and then "Discard Unreadable Data" of the CoralogixConfiguration:

## License

The Coralogix Plugin is licensed under the Apache 2.0 License.

## Additional resources

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

## Support

**Need help?**

Our world-class customer success team is available 24/7 to answer any questions that may come up. Feel free to reach out to us **via our in-app chat** or by sending us an email at [support@coralogix.com](mailto:support@coralogix.com).