# Jenkins

> Send deployment markers to Last9 from Jenkins pipelines and Freestyle jobs to correlate deployments with service performance and error rates.

Source: https://last9.io/docs/integrations/ci-cd/jenkins/

The [Last9 Jenkins Plugin](https://github.com/last9/last9-jenkins-plugin) sends deployment markers to Last9's [Change Events API](/docs/change-events/) from Jenkins Pipeline and Freestyle jobs. Deployment events appear as overlays on your service dashboards, letting you correlate releases with performance changes, error spikes, and APDEX shifts.

API failures never fail your build. The plugin logs a warning and moves on — deployments ship; observability is best-effort.

## Prerequisites

- A Last9 account with an API refresh token (write scope). See [Getting Started with API](/docs/getting-started-with-api/) to generate one.
- Your Last9 organization slug (the `{org}` segment in your Last9 dashboard URL).
- Jenkins 2.462.3 or newer, Java 17 or newer.
- The `environment` value must match the `deployment_environment` label on your APM services for automatic dashboard correlation.

## Setup

**1. Create a credential**

In **Manage Jenkins → Credentials**, add a **Secret text** credential. The secret is your Last9 refresh token.

**2. Configure the plugin**

Go to **Manage Jenkins → System → Last9**:

- **Organization Slug** — your org identifier from the Last9 URL (e.g. `acme`)
- **API Credential** — the credential you just created
- **Default Data Source Name** — optional

Hit **Test Connection** to verify before saving.

## Pipeline

### Deployment window (start + stop)

Send `start` before your deploy, `stop` after. Last9 shows the full window so you can see how performance changed during the rollout.

```groovy
pipeline {
  agent any
  stages {
    stage('Deploy') {
      steps {
        last9DeploymentMarker(
          serviceName: 'payments-api',
          environment: 'production',
          eventState: 'start'
        )
        sh './deploy.sh'
        last9DeploymentMarker(
          serviceName: 'payments-api',
          environment: 'production',
          eventState: 'stop'
        )
      }
    }
  }
}
```

### Single marker

If you only need a point-in-time annotation after the deploy finishes:

```groovy
post {
  success {
    last9DeploymentMarker serviceName: 'payments-api', environment: 'production'
  }
}
```

`eventState` defaults to `stop`.

### All options

```groovy
last9DeploymentMarker(
  serviceName:    'payments-api',       // required
  environment:    'production',         // recommended
  eventState:     'start',              // 'start' or 'stop' (default: 'stop')
  eventName:      'deployment',         // default: 'deployment'
  dataSourceName: 'payments-ds',        // overrides global default
  customAttributes: [
    'deploy.version': '1.4.2',
    'deploy.triggered_by': 'release-bot'
  ],
  // Override global config per-step (useful for multi-team Jenkins)
  orgSlug:      'acme',
  credentialId: 'last9-token-prod'
)
```

## Freestyle Jobs

### Deployment window (start + stop)

Add **Track Last9 Deployment Window (start + stop)** in the **Build Environment** section. Sends `start` before the first build step, `stop` after the last — including on failure.

### Single marker

Add **Send Last9 Deployment Marker** as a post-build action. Configure when to send:

- **Send on Success** (default: on)
- **Send on Failure** (default: off)
- **Send on Unstable** (default: off)
- **Send on Aborted** (default: off)

## Auto-Captured Attributes

These are attached to every event automatically:

| Attribute                   | Source             |
| --------------------------- | ------------------ |
| `scm.commit_sha`            | `$GIT_COMMIT`      |
| `scm.branch`                | `$GIT_BRANCH`      |
| `scm.url`                   | `$GIT_URL`         |
| `scm.author`                | `$GIT_AUTHOR_NAME` |
| `jenkins.job_name`          | build metadata     |
| `jenkins.build_number`      | build metadata     |
| `jenkins.build_url`         | build metadata     |
| `jenkins.build_result`      | build metadata     |
| `jenkins.build_duration_ms` | build metadata     |
| `jenkins.build_user`        | triggered-by user  |
| `jenkins.node_name`         | executor node      |

## Service Dashboard Correlation

For deployment markers to appear as overlays on your Last9 service dashboards, two values must match your APM data exactly:

- `environment` must equal the `deployment_environment` label on your APM services
- `serviceName` must equal the `service` label on your APM services

When both match, every deployment event appears as a vertical marker on your APDEX, response time, throughput, and error rate charts. See [Change Events](/docs/change-events/) for details.

## Multi-Service Pipelines

Each `last9DeploymentMarker` step is independent. Run as many as you need:

```groovy
stage('Deploy Services') {
  parallel {
    stage('API') {
      steps {
        last9DeploymentMarker serviceName: 'api', environment: 'production', eventState: 'start'
        sh './deploy-api.sh'
        last9DeploymentMarker serviceName: 'api', environment: 'production', eventState: 'stop'
      }
    }
    stage('Worker') {
      steps {
        last9DeploymentMarker serviceName: 'worker', environment: 'production', eventState: 'start'
        sh './deploy-worker.sh'
        last9DeploymentMarker serviceName: 'worker', environment: 'production', eventState: 'stop'
      }
    }
  }
}
```

---

## Troubleshooting

Please get in touch with us on [Discord](https://discord.com/invite/Q3p2EEucx9) or [Email](mailto:support@last9.io) if you have any questions.