Defining Jenkins Observer jobs

Using the Jenkins Observer, you can define listen jobs that receive build information generated by the Agile Service Manager plugin for Jenkins.

Before you begin

Ensure you have the Jenkins details to hand.

Remember: Swagger documentation for the observer is available at the following default location: https://<your host>/1.0/jenkins-observer/swagger

About this task

jenkins_observer_common.sh
The configuration file you use to customize Jenkins Observer settings.
The parameters defined here are then used by the jenkins_observer_listen_start.sh script to trigger the Jenkins Observer jobs.
Tip: Alternatively, you can set the appropriate environment variables. If an environment variable is set, it takes precedence over the configuration file settings.
You define and start the following job. You must edit the parameters in the configuration file before running this job.
Listen job
The standalone listen job receives Jenkins build notification data for a specified namespace and processes it as a topology.
The listen job is long-running, and runs until it is explicitly stopped or until the observer is stopped.
This job is started by the jenkins_observer_listen_start.sh script.

Procedure

To edit the parameters in the configuration file

  1. Open the jenkins_observer_common.sh configuration file and edit the following parameters:
    Table 1. Jenkins Observer job parameters
    Parameter Action Details
    Unique ID Enter a unique name for the job. Required
    Jenkins observation namespace Specify a provider namespace with which to associate all the topology data generated by this job. Required
    Access scope

    Enter text to provide a scope for the resources.

    Access scope can help map alerts to resources when resources in different scopes share the same parameters, such as matchTokens.

    		 Optional.
    Tip: You can define access scope for locations, project names, namespaces, etc.
    Generate debug support file
    Set the optional Generate debug support file parameter to 'True' in order to capture the output of the next scheduled job run as a file. This file will be stored with an observer's log files and can be used to debug observer issues, for example at the request of your designated Support team, or while using a test environment. For one-off jobs (that is, Load jobs), this parameter reverts to 'False' after the next completed run. To examine the output produced, you can load the generated debug file using the File Observer. The file is saved to the following locations:
    On-prem
    $ASM_HOME/logs/<obs>-observer/
    On OCP
    /var/log/itsm/<obs>-observer
    		 Optional
    Observer job description Enter additional information to describe the job. Optional
    Job schedule

    Specify when the job should run, and whether it should run at regular intervals.

    By default the job runs immediately, and only once.

    Optionally you can specify a future date and time for the job to run, and then set it to run at regular intervals after that.

    Optional. Transient (one-off) jobs only.

    If you set a job schedule, the run intervals must be at least 90 seconds apart, and if you set them at less than 15 minutes, a warning is displayed, as the frequency can impact system performance.

To start the job

  1. Use the following command: 
    $ASM_HOME/bin/jenkins_observer_listen_start.sh

What to do next

You can also use the following scripts:
jenkins_observer_listen_stop.sh
Stops the Listen job
jenkins_observer_job_list.sh
Lists the status of current jobs
jenkins_observer_log_level.sh
Sets the log level
Remember: As an alternative to being configured using the Observer Configuration UI, observer jobs have scripts to start and stop all available jobs, to list the status of a current job, and to set its logging levels. These scripts can be run with -h or --help to display help information, and with -v or --verbose to print out the details of the actions performed by the script, including the full cURL command. For the on-prem version of Agile Service Manager, observer scripts are configured for specific jobs by editing the script configuration files.