beekeeper.pl 20.9 KB
Newer Older
1
#!/usr/bin/env perl
2 3

use strict;
Leo Gordon's avatar
Leo Gordon committed
4
use warnings;
5
use Getopt::Long;
Leo Gordon's avatar
Leo Gordon committed
6

7
use Bio::EnsEMBL::Hive::Utils ('script_usage', 'destringify');
8 9 10 11 12
use Bio::EnsEMBL::Hive::DBSQL::DBAdaptor;
use Bio::EnsEMBL::Hive::Worker;
use Bio::EnsEMBL::Hive::Queen;
use Bio::EnsEMBL::Hive::URLFactory;
use Bio::EnsEMBL::Hive::DBSQL::AnalysisCtrlRuleAdaptor;
13
use Bio::EnsEMBL::Hive::Valley;
14

Leo Gordon's avatar
Leo Gordon committed
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
main();

sub main {
    $| = 1;
    Bio::EnsEMBL::Registry->no_version_check(1);

        # ok this is a hack, but I'm going to pretend I've got an object here
        # by creating a hash ref and passing it around like an object
        # this is to avoid using global variables in functions, and to consolidate
        # the globals into a nice '$self' package
    my $self = {};

    $self->{'db_conf'} = {
        -host   => '',
        -port   => 3306,
        -user   => 'ensro',
        -pass   => '',
        -dbname => '',
    };

    my ($help, $conf_file);
    my $loopit                      = 0;
    my $sync                        = 0;
    my $local                       = 0;
    my $show_failed_jobs            = 0;
    my $no_pend_adjust              = 0;
41 42
    my $submit_workers_max          = 50;
    my $total_workers_max           = undef;
43
    my $meadow_type                 = undef;
44
    my $meadow_options              = '';
Leo Gordon's avatar
Leo Gordon committed
45
    my $run                         = 0;
46 47
    my $max_loops                   = 0; # not running by default
    my $keep_alive                  = 0; # ==1 means run even when there is nothing to do
Leo Gordon's avatar
Leo Gordon committed
48 49 50 51 52 53 54 55 56
    my $check_for_dead              = 0;
    my $all_dead                    = 0;
    my $remove_analysis_id          = 0;
    my $job_id_for_output           = 0;
    my $show_worker_stats           = 0;
    my $kill_worker_id              = 0;
    my $reset_job_id                = 0;
    my $reset_all_jobs_for_analysis = 0;

57 58 59
    $self->{'reg_conf'}             = undef;
    $self->{'reg_alias'}            = undef;

Leo Gordon's avatar
Leo Gordon committed
60
    $self->{'sleep_minutes'}        = 1;
Leo Gordon's avatar
Leo Gordon committed
61
    $self->{'verbose_stats'}        = 1;
62
    $self->{'retry_throwing_jobs'}  = undef;
63
    $self->{'hive_output_dir'} = undef;
Leo Gordon's avatar
Leo Gordon committed
64

Leo Gordon's avatar
Leo Gordon committed
65
    GetOptions(
Leo Gordon's avatar
Leo Gordon committed
66
                    # connection parameters
67 68 69 70 71 72 73 74 75
               'conf=s'             => \$conf_file,
               'reg_conf|regfile=s' => \$self->{'reg_conf'},
               'reg_alias|regname=s'=> \$self->{'reg_alias'},
               'url=s'              => \$self->{'url'},
               'host|dbhost=s'      => \$self->{'db_conf'}->{'-host'},
               'port|dbport=i'      => \$self->{'db_conf'}->{'-port'},
               'user|dbuser=s'      => \$self->{'db_conf'}->{'-user'},
               'password|dbpass=s'  => \$self->{'db_conf'}->{'-pass'},
               'database|dbname=s'  => \$self->{'db_conf'}->{'-dbname'},
Leo Gordon's avatar
Leo Gordon committed
76 77

                    # loop control
78 79 80 81
               'run'                => \$run,
               'loop'               => \$loopit,
               'max_loops=i'        => \$max_loops,
               'keep_alive'         => \$keep_alive,
82
               'job_id|run_job_id=i'=> \$self->{'run_job_id'},
83
               'sleep=f'            => \$self->{'sleep_minutes'},
Leo Gordon's avatar
Leo Gordon committed
84 85 86

                    # meadow control
               'local!'            => \$local,
87 88
               'total_workers_max|local_cpus=i'  => \$total_workers_max,
               'submit_workers_max|wlimit=i' => \$submit_workers_max,
Leo Gordon's avatar
Leo Gordon committed
89
               'no_pend'           => \$no_pend_adjust,
90
               'meadow_type=s'     => \$meadow_type,
91
               'meadow_options=s'  => \$meadow_options,
Leo Gordon's avatar
Leo Gordon committed
92 93

                    # worker control
94 95
               'job_limit|jlimit=i'     => \$self->{'job_limit'},
               'life_span|lifespan=i'   => \$self->{'life_span'},
96 97
               'logic_name=s'           => \$self->{'logic_name'},
               'hive_output_dir=s'      => \$self->{'hive_output_dir'},
98
               'retry_throwing_jobs=i'  => \$self->{'retry_throwing_jobs'},
99
               'debug=i'                => \$self->{'debug'},
Leo Gordon's avatar
Leo Gordon committed
100 101

                    # other commands/options
Leo Gordon's avatar
Leo Gordon committed
102
               'h|help'            => \$help,
Leo Gordon's avatar
Leo Gordon committed
103 104 105 106 107 108 109 110 111 112 113 114 115
               'sync'              => \$sync,
               'dead'              => \$check_for_dead,
               'killworker=i'      => \$kill_worker_id,
               'alldead'           => \$all_dead,
               'no_analysis_stats' => \$self->{'no_analysis_stats'},
               'verbose_stats=i'   => \$self->{'verbose_stats'},
               'worker_stats'      => \$show_worker_stats,
               'failed_jobs'       => \$show_failed_jobs,
               'reset_job_id=i'    => \$reset_job_id,
               'reset_all|reset_all_jobs_for_analysis=s' => \$reset_all_jobs_for_analysis,
               'delete|remove=s'   => \$remove_analysis_id, # careful
               'job_output=i'      => \$job_id_for_output,
               'monitor!'          => \$self->{'monitor'},
116 117 118

                    # loose arguments interpreted as database name (for compatibility with mysql[dump])
               '<>', sub { $self->{'db_conf'}->{'-dbname'} = shift @_; },
Leo Gordon's avatar
Leo Gordon committed
119 120
    );

121
    if ($help) { script_usage(0); }
Leo Gordon's avatar
Leo Gordon committed
122 123

    parse_conf($self, $conf_file);
124

Leo Gordon's avatar
Leo Gordon committed
125 126
    if($run or $self->{'run_job_id'}) {
        $max_loops = 1;
127
    } elsif ($loopit or $keep_alive) {
Leo Gordon's avatar
Leo Gordon committed
128 129 130 131 132 133 134
        unless($max_loops) {
            $max_loops = -1; # unlimited
        }
        unless(defined($self->{'monitor'})) {
            $self->{'monitor'} = 1;
        }
    }
135

136 137 138
    if($self->{'reg_conf'} and $self->{'reg_alias'}) {
        Bio::EnsEMBL::Registry->load_all($self->{'reg_conf'});
        $self->{'dba'} = Bio::EnsEMBL::Registry->get_DBAdaptor($self->{'reg_alias'}, 'hive');
Leo Gordon's avatar
Leo Gordon committed
139 140 141 142 143 144 145 146
    } elsif($self->{'url'}) {
        $self->{'dba'} = Bio::EnsEMBL::Hive::URLFactory->fetch($self->{'url'}) || die("Unable to connect to $self->{'url'}\n");
    } elsif (    $self->{'db_conf'}->{'-host'}
             and $self->{'db_conf'}->{'-user'}
             and $self->{'db_conf'}->{'-dbname'}) { # connect to database specified
                    $self->{'dba'} = new Bio::EnsEMBL::Hive::DBSQL::DBAdaptor(%{$self->{'db_conf'}});
                    $self->{'url'} = $self->{'dba'}->dbc->url;
    } else {
147
        print "\nERROR : Connection parameters (reg_conf+reg_alias, url or dbhost+dbuser+dbname) need to be specified\n\n";
148
        script_usage(1);
Leo Gordon's avatar
Leo Gordon committed
149
    }
150

Leo Gordon's avatar
Leo Gordon committed
151 152
    my $queen = $self->{'dba'}->get_Queen;
    $queen->{'verbose_stats'} = $self->{'verbose_stats'};
153

154 155 156 157
    my $pipeline_name = destringify(
            $self->{'dba'}->get_MetaContainer->list_value_by_key("pipeline_name")->[0]
         || $self->{'dba'}->get_MetaContainer->list_value_by_key("name")->[0]
    );
158

159 160 161 162 163 164 165 166 167 168 169 170 171 172
    unless($pipeline_name) {
        print STDERR "+---------------------------------------------------------------------+\n";
        print STDERR "!                                                                     !\n";
        print STDERR "!                  WARNING:                                           !\n";
        print STDERR "!                                                                     !\n";
        print STDERR "! At the moment your pipeline doesn't have 'pipeline_name' defined.   !\n";
        print STDERR "! This may seriously impair your beekeeping experience unless you are !\n";
        print STDERR "! the only farm user. The name should be set in your PipeConfig file, !\n";
        print STDERR "! or if you are running an old pipeline you can just set it by hand   !\n";
        print STDERR "! in the 'meta' table.                                                !\n";
        print STDERR "!                                                                     !\n";
        print STDERR "+---------------------------------------------------------------------+\n";
    }

173
    $meadow_type = 'LOCAL' if($local);
174
    my $valley = Bio::EnsEMBL::Hive::Valley->new( $meadow_type );
175

176 177 178 179 180 181 182
    my $current_meadow = $valley->get_current_meadow();
    warn "Current meadow: ".$current_meadow->toString."\n";

    $current_meadow->pipeline_name($pipeline_name);
    $current_meadow->meadow_options($meadow_options);
    $current_meadow->total_running_workers_max($total_workers_max) if($total_workers_max);
    $current_meadow->pending_adjust(not $no_pend_adjust);
Leo Gordon's avatar
Leo Gordon committed
183 184

    if($self->{'run_job_id'}) {
185
        $submit_workers_max = 1;
Leo Gordon's avatar
Leo Gordon committed
186
    }
187
    $current_meadow->submit_workers_max($submit_workers_max);
188

Leo Gordon's avatar
Leo Gordon committed
189
    if($reset_job_id) { $queen->reset_and_fetch_job_by_dbID($reset_job_id); }
190

Leo Gordon's avatar
Leo Gordon committed
191 192 193 194 195
    if($job_id_for_output) {
        printf("===== job output\n");
        my $job = $self->{'dba'}->get_AnalysisJobAdaptor->fetch_by_dbID($job_id_for_output);
        $job->print_job();
    }
196

Leo Gordon's avatar
Leo Gordon committed
197 198 199
    if($reset_all_jobs_for_analysis) {
        reset_all_jobs_for_analysis($self, $reset_all_jobs_for_analysis)
    }
200

Leo Gordon's avatar
Leo Gordon committed
201 202
    if($remove_analysis_id) { remove_analysis_id($self, $remove_analysis_id); }
    if($all_dead)           { $queen->register_all_workers_dead(); }
203
    if($check_for_dead)     { $queen->check_for_dead_workers($current_meadow, 1); }
Javier Herrero's avatar
Javier Herrero committed
204

Leo Gordon's avatar
Leo Gordon committed
205
    if ($kill_worker_id) {
206
        my $worker = $queen->fetch_by_dbID($kill_worker_id);
Javier Herrero's avatar
Javier Herrero committed
207

208 209 210 211 212 213
        unless( $worker->cause_of_death() ) {
            if( my $meadow = $valley->find_available_meadow_responsible_for_worker( $worker ) ) {

                printf("Killing worker: %10d %35s %15s  %20s(%d) : ", 
                        $worker->dbID, $worker->host, $worker->process_id, 
                        $worker->analysis->logic_name, $worker->analysis->dbID);
Javier Herrero's avatar
Javier Herrero committed
214

215 216 217 218 219 220 221 222 223
                $meadow->kill_worker($worker);
                $worker->cause_of_death('KILLED_BY_USER');
                $queen->register_worker_death($worker);
                     # what about clean-up? Should we do it here or not?
            } else {
                die "Could not access meadow responsible for worker (dbID=$kill_worker_id), so cannot kill";
            }
        } else {
            die "Worker (dbID=$kill_worker_id) already dead, so cannot kill";
Leo Gordon's avatar
Leo Gordon committed
224 225
        }
    }
Javier Herrero's avatar
Javier Herrero committed
226

Leo Gordon's avatar
Leo Gordon committed
227
    my $analysis = $self->{'dba'}->get_AnalysisAdaptor->fetch_by_logic_name($self->{'logic_name'});
228

Leo Gordon's avatar
Leo Gordon committed
229
    if ($max_loops) { # positive $max_loop means limited, negative means unlimited
230

231
        run_autonomously($self, $max_loops, $keep_alive, $queen, $current_meadow, $analysis);
Javier Herrero's avatar
Javier Herrero committed
232

Leo Gordon's avatar
Leo Gordon committed
233 234
    } else {
            # the output of several methods will look differently depending on $analysis being [un]defined
235

Leo Gordon's avatar
Leo Gordon committed
236 237 238 239 240
        if($sync) {
            $queen->synchronize_hive($analysis);
        }
        $queen->print_analysis_status($analysis) unless($self->{'no_analysis_stats'});
        $queen->print_running_worker_status;
241

Leo Gordon's avatar
Leo Gordon committed
242
        show_running_workers($self, $queen) if($show_worker_stats);
243

244
        $queen->schedule_workers($analysis);    # show what would be submitted, but do not actually submit
Leo Gordon's avatar
Leo Gordon committed
245
        $queen->get_remaining_jobs_show_hive_progress();
246

Leo Gordon's avatar
Leo Gordon committed
247 248 249
        if($show_failed_jobs) {
            print("===== failed jobs\n");
            my $failed_job_list = $self->{'dba'}->get_AnalysisJobAdaptor->fetch_all_failed_jobs();
250

Leo Gordon's avatar
Leo Gordon committed
251 252 253 254 255
            foreach my $job (@{$failed_job_list}) {
                $job->print_job();
            }
        }
    }
Javier Herrero's avatar
Javier Herrero committed
256

Leo Gordon's avatar
Leo Gordon committed
257 258 259
    if ($self->{'monitor'}) {
        $queen->monitor();
    }
260

Leo Gordon's avatar
Leo Gordon committed
261
    exit(0);
262 263
}

264 265 266 267 268 269 270 271
#######################
#
# subroutines
#
#######################


sub parse_conf {
Leo Gordon's avatar
Leo Gordon committed
272
    my ($self, $conf_file) = @_;
273 274 275 276 277 278 279 280 281 282 283 284 285 286

  if($conf_file and (-e $conf_file)) {
    #read configuration file from disk
    my @conf_list = @{do $conf_file};

    foreach my $confPtr (@conf_list) {
      #print("HANDLE type " . $confPtr->{TYPE} . "\n");
      if(($confPtr->{TYPE} eq 'COMPARA') or ($confPtr->{TYPE} eq 'DATABASE')) {
        $self->{'db_conf'} = $confPtr;
      }
    }
  }
}

Leo Gordon's avatar
Leo Gordon committed
287 288

# --------------[worker reports]--------------------
289

Leo Gordon's avatar
Leo Gordon committed
290 291
sub show_given_workers {
    my ($self, $worker_list, $verbose_stats) = @_;
292

Leo Gordon's avatar
Leo Gordon committed
293 294
    foreach my $worker (@{$worker_list}) {
        printf("%10d %35s(%5d) %5s:%15s %15s (%s)\n", 
295
            $worker->dbID,
Leo Gordon's avatar
Leo Gordon committed
296 297 298 299 300 301
            $worker->analysis->logic_name,
            $worker->analysis->dbID,
            $worker->beekeeper,
            $worker->process_id, 
            $worker->host,
            $worker->last_check_in);
302
        printf("%s\n", $worker->worker_output_dir) if ($verbose_stats);
Leo Gordon's avatar
Leo Gordon committed
303
    }
304 305
}

Leo Gordon's avatar
Leo Gordon committed
306 307
sub show_running_workers {
    my ($self, $queen) = @_;
308

Leo Gordon's avatar
Leo Gordon committed
309 310
    print("===== running workers\n");
    show_given_workers($self, $queen->fetch_overdue_workers(0), $queen->{'verbose_stats'});
311 312 313
}


Leo Gordon's avatar
Leo Gordon committed
314
sub generate_worker_cmd {
Leo Gordon's avatar
Leo Gordon committed
315
    my ($self) = @_;
316

317 318 319 320 321 322 323 324 325 326 327 328
    my $worker_cmd = 'runWorker.pl';

    if ($self->{'reg_conf'}) {      # if reg_conf is defined, we have to pass it anyway, regardless of whether it is used to connect to the Hive database or not:
        $worker_cmd .= ' -reg_conf '. $self->{'reg_conf'};
    }

    if ($self->{'reg_alias'}) {     # then we pass the connection parameters:
        $worker_cmd .= ' -reg_alias '. $self->{'reg_alias'};
    } else {
        $worker_cmd .= ' -url '. $self->{'url'};
    }

Leo Gordon's avatar
Leo Gordon committed
329 330 331
    if ($self->{'run_job_id'}) {
        $worker_cmd .= " -job_id ".$self->{'run_job_id'};
    } else {
332
        foreach my $worker_option ('job_limit', 'life_span', 'logic_name', 'retry_throwing_jobs', 'hive_output_dir', 'debug') {
333 334 335 336
            if(defined(my $value = $self->{$worker_option})) {
                $worker_cmd .= " -${worker_option} $value";
            }
        }
Leo Gordon's avatar
Leo Gordon committed
337
    }
338

Leo Gordon's avatar
Leo Gordon committed
339
    return $worker_cmd;
340 341 342
}

sub run_autonomously {
343
    my ($self, $max_loops, $keep_alive, $queen, $current_meadow, $this_analysis) = @_;
344

Leo Gordon's avatar
Leo Gordon committed
345 346 347
    unless(`runWorker.pl`) {
        print("can't find runWorker.pl script.  Please make sure it's in your path\n");
        exit(1);
348 349
    }

Leo Gordon's avatar
Leo Gordon committed
350 351
    my $worker_cmd = generate_worker_cmd($self);

Leo Gordon's avatar
Leo Gordon committed
352
        # pre-hash the resource_class xparams for future use:
353
    my $rc_xparams = $self->{'dba'}->get_ResourceDescriptionAdaptor->fetch_by_meadow_type_HASHED_FROM_rc_id_TO_parameters($current_meadow->type());
Leo Gordon's avatar
Leo Gordon committed
354

Leo Gordon's avatar
Leo Gordon committed
355 356 357 358 359 360 361 362 363
    my $iteration=0;
    my $num_of_remaining_jobs=0;
    my $failed_analyses=0;
    do {
        if($iteration++) {
            $queen->monitor();
            $self->{'dba'}->dbc->disconnect_if_idle;
            printf("sleep %.2f minutes. Next loop at %s\n", $self->{'sleep_minutes'}, scalar localtime(time+$self->{'sleep_minutes'}*60));
            sleep($self->{'sleep_minutes'}*60);  
364
        }
365

Leo Gordon's avatar
Leo Gordon committed
366
        print("\n======= beekeeper loop ** $iteration **==========\n");
Javier Herrero's avatar
Javier Herrero committed
367

368
        $queen->check_for_dead_workers($current_meadow, 0);
369

Leo Gordon's avatar
Leo Gordon committed
370 371
        $queen->print_analysis_status unless($self->{'no_analysis_stats'});
        $queen->print_running_worker_status;
Leo Gordon's avatar
Leo Gordon committed
372

373
        my $workers_to_run_by_rc_id = $queen->schedule_workers_resync_if_necessary($current_meadow, $this_analysis);
374

375
        if(keys %$workers_to_run_by_rc_id) {
376 377
            foreach my $rc_id ( sort { $workers_to_run_by_rc_id->{$a}<=>$workers_to_run_by_rc_id->{$b} } keys %$workers_to_run_by_rc_id) {
                my $this_rc_worker_count = $workers_to_run_by_rc_id->{$rc_id};
378

379
                print "Submitting $this_rc_worker_count workers (rc_id=$rc_id) to ".$current_meadow->type()."\n";
Leo Gordon's avatar
Leo Gordon committed
380

381
                $current_meadow->submit_workers($iteration, $worker_cmd, $this_rc_worker_count, $rc_id, $rc_xparams->{$rc_id} || '');
Leo Gordon's avatar
Leo Gordon committed
382
            }
Leo Gordon's avatar
Leo Gordon committed
383 384 385
        } else {
            print "Not submitting any workers this iteration\n";
        }
386

Leo Gordon's avatar
Leo Gordon committed
387
        $failed_analyses       = $queen->get_num_failed_analyses($this_analysis);
Leo Gordon's avatar
Leo Gordon committed
388
        $num_of_remaining_jobs = $queen->get_remaining_jobs_show_hive_progress();
389

390 391
    } while( $keep_alive
            or (!$failed_analyses and $num_of_remaining_jobs and $iteration!=$max_loops) );
392

Leo Gordon's avatar
Leo Gordon committed
393 394 395 396 397 398
    print "The Beekeeper has stopped because ".(
          $failed_analyses ? "there were $failed_analyses failed analyses"
        : !$num_of_remaining_jobs ? "there is nothing left to do"
        : "the number of loops was limited by $max_loops and this limit expired"
    )."\n";

Leo Gordon's avatar
Leo Gordon committed
399
    printf("dbc %d disconnect cycles\n", $self->{'dba'}->dbc->disconnect_count);
400 401
}

402
sub reset_all_jobs_for_analysis {
Leo Gordon's avatar
Leo Gordon committed
403
    my ($self, $logic_name) = @_;
404
  
Leo Gordon's avatar
Leo Gordon committed
405
  my $analysis = $self->{'dba'}->get_AnalysisAdaptor->fetch_by_logic_name($logic_name)
406
      || die( "Cannot AnalysisAdaptor->fetch_by_logic_name($logic_name)"); 
407 408 409 410
  
  $self->{'dba'}->get_AnalysisJobAdaptor->reset_all_jobs_for_analysis_id($analysis->dbID); 
  $self->{'dba'}->get_Queen->synchronize_AnalysisStats($analysis->stats);
}
411 412

sub remove_analysis_id {
Leo Gordon's avatar
Leo Gordon committed
413
    my ($self, $analysis_id) = @_;
414

Leo Gordon's avatar
Leo Gordon committed
415 416 417 418 419 420
    require Bio::EnsEMBL::DBSQL::AnalysisAdaptor or die "$!";

    my $analysis = $self->{'dba'}->get_AnalysisAdaptor->fetch_by_dbID($analysis_id); 

    $self->{'dba'}->get_AnalysisJobAdaptor->remove_analysis_id($analysis->dbID); 
    $self->{'dba'}->get_AnalysisAdaptor->remove($analysis); 
421
}
Leo Gordon's avatar
Leo Gordon committed
422

423 424 425 426 427 428 429 430 431 432
__DATA__

=pod

=head1 NAME

    beekeeper.pl

=head1 DESCRIPTION

Leo Gordon's avatar
Leo Gordon committed
433 434 435
    The Beekeeper is in charge of interfacing between the Queen and a compute resource or 'compute farm'.
    Its job is to initialize/sync the eHive database (via the Queen), query the Queen if it needs any workers
    and to send the requested number of workers to open machines via the runWorker.pl script.
Leo Gordon's avatar
Leo Gordon committed
436

Leo Gordon's avatar
Leo Gordon committed
437
    It is also responsible for interfacing with the Queen to identify workers which died
438
    unexpectedly so that she can free the dead workers and reclaim unfinished jobs.
439 440 441

=head1 USAGE EXAMPLES

Leo Gordon's avatar
Leo Gordon committed
442
        # Usually run after the pipeline has been created to calculate the internal statistics necessary for eHive functioning
443
    beekeeper.pl --host=hostname --port=3306 --user=username --password=secret ehive_dbname -sync
444

Leo Gordon's avatar
Leo Gordon committed
445 446
        # An alternative way of doing the same thing
    beekeeper.pl -url mysql://username:secret@hostname:port/ehive_dbname -sync
447

Leo Gordon's avatar
Leo Gordon committed
448 449
        # Do not run any additional Workers, just check for the current status of the pipeline:
    beekeeper.pl -url mysql://username:secret@hostname:port/ehive_dbname
Leo Gordon's avatar
Leo Gordon committed
450

451 452
        # Run the pipeline in automatic mode (-loop), run all the workers locally (-meadow_type LOCAL) and allow for 3 parallel workers (-total_workers_max 3)
    beekeeper.pl -url mysql://username:secret@hostname:port/long_mult_test -meadow_type LOCAL -total_workers_max 3 -loop
453

Leo Gordon's avatar
Leo Gordon committed
454 455
        # Run in automatic mode, but only restrict to running the 'fast_blast' analysis
    beekeeper.pl -url mysql://username:secret@hostname:port/long_mult_test -logic_name fast_blast -loop
456

Leo Gordon's avatar
Leo Gordon committed
457 458
        # Restrict the normal execution to one iteration only - can be used for testing a newly set up pipeline
    beekeeper.pl -url mysql://username:secret@hostname:port/long_mult_test -run
459

Leo Gordon's avatar
Leo Gordon committed
460 461
        # Reset all 'buggy_analysis' jobs to 'READY' state, so that they can be run again
    beekeeper.pl -url mysql://username:secret@hostname:port/long_mult_test -reset_all_jobs_for_analysis buggy_analysis
462

Leo Gordon's avatar
Leo Gordon committed
463 464
        # Do a cleanup: find and bury dead workers, reclaim their jobs
    beekeeper.pl -url mysql://username:secret@hostname:port/long_mult_test -dead
465 466 467 468 469

=head1 OPTIONS

=head2 Connection parameters

Leo Gordon's avatar
Leo Gordon committed
470
    -conf <path>           : config file describing db connection
471 472
    -reg_conf <path>       : path to a Registry configuration file
    -reg_alias <string>    : species/alias name for the Hive DBAdaptor
Leo Gordon's avatar
Leo Gordon committed
473 474 475 476 477
    -url <url string>      : url defining where hive database is located
    -host <machine>        : mysql database host <machine>
    -port <port#>          : mysql port number
    -user <name>           : mysql connection user <name>
    -password <pass>       : mysql connection password <pass>
478
    [-database] <name>     : mysql database <name>
479 480 481

=head2 Looping control

Leo Gordon's avatar
Leo Gordon committed
482 483
    -loop                  : run autonomously, loops and sleeps
    -max_loops <num>       : perform max this # of loops in autonomous mode
484
    -keep_alive            : do not stop when there are no more jobs to do - carry on looping
Leo Gordon's avatar
Leo Gordon committed
485
    -job_id <job_id>       : run 1 iteration for this job_id
486
    -run                   : run 1 iteration of automation loop
Leo Gordon's avatar
Leo Gordon committed
487
    -sleep <num>           : when looping, sleep <num> minutes (default 2min)
488 489 490

=head2 Meadow control

491 492
    -total_workers_max <num>  : max # workers to be running in parallel
    -submit_workers_max <num> : max # workers to create per loop
Leo Gordon's avatar
Leo Gordon committed
493
    -no_pend                  : don't adjust needed workers by pending workers
494
    -meadow_type <string>     : the desired Meadow class name, such as 'LSF' or 'LOCAL'
Leo Gordon's avatar
Leo Gordon committed
495
    -meadow_options <string>  : passes <string> to the Meadow submission command as <options> (formerly lsf_options)
496 497 498

=head2 Worker control

499
    -job_limit <num>            : #jobs to run before worker can die naturally
500
    -life_span <num>            : life_span limit for each worker
501 502 503
    -logic_name <string>        : restrict the pipeline stat/runs to this analysis logic_name
    -retry_throwing_jobs 0|1    : if a job dies *knowingly*, should we retry it by default?
    -hive_output_dir <path>     : directory where stdout/stderr of the hive is redirected
504
    -debug <debug_level>        : set debug level of the workers
505 506 507

=head2 Other commands/options

Leo Gordon's avatar
Leo Gordon committed
508 509 510 511 512 513 514 515 516
    -help                  : print this help
    -dead                  : clean dead jobs for resubmission
    -alldead               : all outstanding workers
    -no_analysis_stats     : don't show status of each analysis
    -worker_stats          : show status of each running worker
    -failed_jobs           : show all failed jobs
    -reset_job_id <num>    : reset a job back to READY so it can be rerun
    -reset_all_jobs_for_analysis <logic_name>
                           : reset jobs back to READY so they can be rerun
517

Leo Gordon's avatar
Leo Gordon committed
518 519
=head1 CONTACT

Leo Gordon's avatar
Leo Gordon committed
520
    Please contact ehive-users@ebi.ac.uk mailing list with questions/suggestions.
Leo Gordon's avatar
Leo Gordon committed
521

522 523
=cut