KBEC-00216 - Available CloudBees CD (CloudBees Flow) specific debug methods

Article ID:360033192431
4 minute readKnowledge base

Description

Plugins run on the Web Server as the Web Server user using the session ID of the user who is logged into CloudBees CD (CloudBees Flow) through the Web UI.

You want to see what is happening at the Web Server level when the SCM plugin does not work.

Or you are having an ectool connection problem and you want to know the details of communication to the server.

This article shows several debug techniques used for enhanced CloudBees CD (CloudBees Flow) debug.

Have the Web Server print extra messages

More step logs messages

If you place text "\&debug=1" on the end of URL when on the "Admin->Source Control" page, additional information is provided in the browser output.

This is a one shot debug as the web server drops the debug unless it is entered by hand on the next URL.

Consider the following:

  1. Debug CGI messages are placed on the screen.

  2. Plugins use jobs to carry out some functionality. The job created by the CGI will not be automatically deleted so it can be inspected post CGI operation.

More apache error.log messages

The normal access.log information show the total elapsed time of each Web Server request. Each request is made up of sub-requests for data.

By turning on traceRequests in config.php the apache error.log file will have an entry for each web server sub-request. These message sub-requests can be directly correlated to the commander.log request for data. The sub-requests can now be used to find out the operational time syncs.

Modify config.php to contain the following line:

$config["traceRequests"] = true;

After your tests, remove the traceRequests entry as there are voluminous messages placed in error.log which will eventually fill up the disk because error.log does not roll over.

Have Preflight print extra messages into the step log

Use "ecclientpreflight --debug" to create extra step log output that is useful for analyzing problems.

Have ectool print additional communication information to the terminal

  1. Use "ectool --debug 1" to create extra output that is useful for analyzing problems. The information will include:

    1. timestamp

    2. the server communication messages

  2. You can change the ElectricCommander.pm package on an agent to have all ectool commands run in debug mode

    1. look for code of the form

       $self->{debug} = 0 unless defined($self->{debug});
    2. and just update it:

       $self->{debug} = 1;
  3. run the test and then restore ElectricCommander.pm to it’s original state.

Have ec-perl print additional information to a file or the terminal

  1. Use debug 1 when starting perl to create extra output that is useful for analyzing problems. The following perl code fragment will print to the screen perl debug messages.

     use strict;
     use ElectricCommander;
     my $ec = new ElectricCommander({debug=>1});
     $ec->login('admin', 'changeme');
     my $xPath = $ec->getProperty("/projects/Performance/procedures/BatchImport/procedureName");
     print $xPath->findvalue("//value"), "\n";
  2. use the following modification to output the messages to a file:

     my $ec = new ElectricCommander({debug=>1, logFile => "/var/tmp/scratch.log"});
  3. when running ec-perl in a step the output file can be named as follows:

     my $ec = new ElectricCommander({debug=>1, logFile => "/var/tmp/scratch-$[jobStepId].log"});

Debugging javascript without running a step or workflow

Debugging javascript by running a job or workflow again and again, well there just has to be a better way.

  1. Put the $[/javascript] block into a property on a step or in a workflow

  2. Get the property value using ectool with the explicit context of a known job or workflow. For example:

     DOLLAR="$"
     DOUBLE='"'
     #for job javascript debug
     ectool setProperty /projects[testing]/job_steps --value "$DOLLAR[/javascript myJob[${DOUBLE}Pass Rate$DOUBLE]>77]" --jobId job_201301011526_J64802
     ectool getProperty "/projects[testing]/job_steps" --jobId job_201301011526_J64802
     #for workflow javascript debug
     ectool setProperty testJavascript --value "$DOLLAR[/javascript myState[${DOUBLE}Pass Rate$DOUBLE]>77]" --workflowName workflow_1_201102011936 --projectName A --stateName Ystate
     ectool getProperty testJavascript --workflowName workflow_1_201102011936 --projectName A --stateName Ystate

    Using this method there is no need to run new EC jobs or workflows every time to test a Javascript change, just get the value of the property.

A Few Agent Debugging Tips

Each Command step runs on the agent in a separate shell instance - so Environment variables set in one Command step will not be effective in the following steps. Environment variables need to be set for each step they are needed in, or made in the startup scripts for the user used by the agent.

By default, the commands in a Command step are run as the user that the agent was installed as, unless Impersonation is used.

To determine why a step may run successfully on one agent and not another, the first thing to do is run a step to gather environment information, with commands such as "whoami", and "env". These are useful if you are getting an error indicating a program is not found in the path.

Running Multiple Commands in a single CloudBees CD (CloudBees Flow) Step

When running multiple shell commands within a single CloudBees CD (CloudBees Flow) Step, the return code will be for the final command in the list of commands. So if you have the following commands in your CloudBees CD (CloudBees Flow) Step:

ls /tmp/foo
ls /tmp

If the first line fails, but the second line succeeds, there status on the step will be Success. The status is only reported on the last command that is run. Running each command in its own step, or creating a script with error checking is the best way to handle this if running multiple commands in a single CloudBees CD (CloudBees Flow) is important to your process.