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

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

8
use Bio::EnsEMBL::Hive::Utils 'destringify';
9 10 11 12 13 14
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;

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 41 42 43 44 45 46
use Bio::EnsEMBL::Hive::Meadow::LSF;
use Bio::EnsEMBL::Hive::Meadow::LOCAL;

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;
    my $worker_limit                = 50;
    my $local_cpus                  = 2;
47
    my $meadow_options              = '';
Leo Gordon's avatar
Leo Gordon committed
48 49 50 51 52 53 54 55 56 57 58
    my $max_loops                   = 0; # not running by default
    my $run                         = 0;
    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;

Leo Gordon's avatar
Leo Gordon committed
59
    $self->{'sleep_minutes'}        = 1;
60
#    $self->{'overdue_minutes'}      = 60;   # which means one hour
Leo Gordon's avatar
Leo Gordon committed
61 62 63
    $self->{'verbose_stats'}        = 1;
    $self->{'reg_name'}             = 'hive';
    $self->{'maximise_concurrency'} = 0;
64
    $self->{'retry_throwing_jobs'}  = undef;
65
    $self->{'hive_output_dir'} = undef;
Leo Gordon's avatar
Leo Gordon committed
66

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

                    # loop control
               'loop'              => \$loopit,
               'max_loops=i'       => \$max_loops,
               'run'               => \$run,
Leo Gordon's avatar
Leo Gordon committed
83
               'job_id|run_job_id=i'  => \$self->{'run_job_id'},
Leo Gordon's avatar
Leo Gordon committed
84 85 86 87 88 89 90
               'sleep=f'           => \$self->{'sleep_minutes'},

                    # meadow control
               'local!'            => \$local,
               'local_cpus=i'      => \$local_cpus,
               'wlimit=i'          => \$worker_limit,
               'no_pend'           => \$no_pend_adjust,
91
               'meadow_options|lsf_options=s'  => \$meadow_options, # 'lsf_options' is deprecated (please investigate the resource requirements, they may suit your needs way better)
Leo Gordon's avatar
Leo Gordon committed
92 93

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

                    # other commands/options
Leo Gordon's avatar
Leo Gordon committed
103
               'h|help'            => \$help,
Leo Gordon's avatar
Leo Gordon committed
104 105 106
               'sync'              => \$sync,
               'dead'              => \$check_for_dead,
               'killworker=i'      => \$kill_worker_id,
107
#               'overdue'           => \$self->{'overdue_minutes'},
Leo Gordon's avatar
Leo Gordon committed
108 109 110 111 112 113 114 115 116 117
               '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'},
118 119 120

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

123
    if ($help) { usage(0); }
Leo Gordon's avatar
Leo Gordon committed
124 125

    parse_conf($self, $conf_file);
126

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

Leo Gordon's avatar
Leo Gordon committed
138 139 140 141 142 143 144 145 146 147 148 149
    if($self->{'reg_file'}) {
        Bio::EnsEMBL::Registry->load_all($self->{'reg_file'});
        $self->{'dba'} = Bio::EnsEMBL::Registry->get_DBAdaptor($self->{'reg_name'}, 'hive');
    } 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 {
        print "\nERROR : Connection parameters (regfile+regname, url or dbhost+dbuser+dbname) need to be specified\n\n";
150
        usage(1);
Leo Gordon's avatar
Leo Gordon committed
151
    }
152

Leo Gordon's avatar
Leo Gordon committed
153 154 155
    my $queen = $self->{'dba'}->get_Queen;
    $queen->{'maximise_concurrency'} = 1 if ($self->{'maximise_concurrency'});
    $queen->{'verbose_stats'} = $self->{'verbose_stats'};
156

157 158 159 160
    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]
    );
161 162 163 164 165 166

    if($local) {
        $self->{'meadow'} = Bio::EnsEMBL::Hive::Meadow::LOCAL->new();
        $self->{'meadow'} -> total_running_workers_limit($local_cpus);
    } else {
        $self->{'meadow'} = Bio::EnsEMBL::Hive::Meadow::LSF->new();
167
        $self->{'meadow'} -> meadow_options($meadow_options);
168 169
    }
    $self->{'meadow'} -> pending_adjust(not $no_pend_adjust);
Leo Gordon's avatar
Leo Gordon committed
170 171 172 173

    if($self->{'run_job_id'}) {
        $worker_limit = 1;
    }
174 175
    $self->{'meadow'} -> submitted_workers_limit($worker_limit);
    $self->{'meadow'} -> pipeline_name($pipeline_name);
176

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

Leo Gordon's avatar
Leo Gordon committed
179 180 181 182 183
    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();
    }
184

Leo Gordon's avatar
Leo Gordon committed
185 186 187
    if($reset_all_jobs_for_analysis) {
        reset_all_jobs_for_analysis($self, $reset_all_jobs_for_analysis)
    }
188

Leo Gordon's avatar
Leo Gordon committed
189 190
    if($remove_analysis_id) { remove_analysis_id($self, $remove_analysis_id); }
    if($all_dead)           { $queen->register_all_workers_dead(); }
Leo Gordon's avatar
Leo Gordon committed
191
    if($check_for_dead)     { $queen->check_for_dead_workers($self->{'meadow'}, 1); }
Javier Herrero's avatar
Javier Herrero committed
192

Leo Gordon's avatar
Leo Gordon committed
193
    if ($kill_worker_id) {
Leo Gordon's avatar
Leo Gordon committed
194
        my $worker = $queen->fetch_by_worker_id($kill_worker_id);
Leo Gordon's avatar
Leo Gordon committed
195 196
        if( $self->{'meadow'}->responsible_for_worker($worker)
        and not defined($worker->cause_of_death())) {
Javier Herrero's avatar
Javier Herrero committed
197

Leo Gordon's avatar
Leo Gordon committed
198
            printf("KILL: %10d %35s %15s  %20s(%d) : ", 
Leo Gordon's avatar
Leo Gordon committed
199
                $worker->worker_id, $worker->host, $worker->process_id, 
Leo Gordon's avatar
Leo Gordon committed
200
                $worker->analysis->logic_name, $worker->analysis->dbID);
Javier Herrero's avatar
Javier Herrero committed
201

Leo Gordon's avatar
Leo Gordon committed
202
            $self->{'meadow'}->kill_worker($worker);
203
            $worker->cause_of_death('KILLED_BY_USER');
Leo Gordon's avatar
Leo Gordon committed
204
            $queen->register_worker_death($worker);
205
                # what about clean-up? Should we do it here or not?
Leo Gordon's avatar
Leo Gordon committed
206 207
        }
    }
Javier Herrero's avatar
Javier Herrero committed
208

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

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

Leo Gordon's avatar
Leo Gordon committed
213
        run_autonomously($self, $max_loops, $queen, $analysis);
Javier Herrero's avatar
Javier Herrero committed
214

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

Leo Gordon's avatar
Leo Gordon committed
218 219 220 221 222
        if($sync) {
            $queen->synchronize_hive($analysis);
        }
        $queen->print_analysis_status($analysis) unless($self->{'no_analysis_stats'});
        $queen->print_running_worker_status;
223

Leo Gordon's avatar
Leo Gordon committed
224 225
        show_running_workers($self, $queen) if($show_worker_stats);
        #show_failed_workers($self, $queen);
226

Leo Gordon's avatar
Leo Gordon committed
227
        $queen->get_num_needed_workers($analysis); # apparently run not for the return value, but for the side-effects
Leo Gordon's avatar
Leo Gordon committed
228
        $queen->get_remaining_jobs_show_hive_progress();
229

Leo Gordon's avatar
Leo Gordon committed
230 231 232
        if($show_failed_jobs) {
            print("===== failed jobs\n");
            my $failed_job_list = $self->{'dba'}->get_AnalysisJobAdaptor->fetch_all_failed_jobs();
233

Leo Gordon's avatar
Leo Gordon committed
234 235 236 237 238
            foreach my $job (@{$failed_job_list}) {
                $job->print_job();
            }
        }
    }
Javier Herrero's avatar
Javier Herrero committed
239

Leo Gordon's avatar
Leo Gordon committed
240 241 242
    if ($self->{'monitor'}) {
        $queen->monitor();
    }
243

Leo Gordon's avatar
Leo Gordon committed
244
    exit(0);
245 246
}

247 248 249 250 251 252 253
#######################
#
# subroutines
#
#######################

sub usage {
254 255 256 257 258 259 260 261 262 263 264 265 266
    my $retvalue = shift @_;

    if(`which perldoc`) {
        system('perldoc', $0);
    } else {
        foreach my $line (<DATA>) {
            if($line!~s/\=\w+\s?//) {
                $line = "\t$line";
            }
            print $line;
        }
    }
    exit($retvalue);
267 268 269
}

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

  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
285 286

# --------------[worker reports]--------------------
287

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

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

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

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

311
sub show_failed_workers {  # does not seem to be used
Leo Gordon's avatar
Leo Gordon committed
312
    my ($self, $queen) = @_;
313

Leo Gordon's avatar
Leo Gordon committed
314 315
    print("===== CRASHED workers\n");
    show_given_workers($self, $queen->fetch_failed_workers(), $queen->{'verbose_stats'});
316 317
}

Leo Gordon's avatar
Leo Gordon committed
318
sub generate_worker_cmd {
Leo Gordon's avatar
Leo Gordon committed
319
    my ($self) = @_;
320

Leo Gordon's avatar
Leo Gordon committed
321
    my $worker_cmd = 'runWorker.pl';   # -bk '. $self->{'meadow'}->type();
Leo Gordon's avatar
Leo Gordon committed
322 323 324
    if ($self->{'run_job_id'}) {
        $worker_cmd .= " -job_id ".$self->{'run_job_id'};
    } else {
325
        foreach my $worker_option ('batch_size', 'job_limit', 'life_span', 'logic_name', 'maximize_concurrency', 'retry_throwing_jobs', 'hive_output_dir') {
326 327 328 329
            if(defined(my $value = $self->{$worker_option})) {
                $worker_cmd .= " -${worker_option} $value";
            }
        }
Leo Gordon's avatar
Leo Gordon committed
330
    }
331

Leo Gordon's avatar
Leo Gordon committed
332 333 334 335 336
    if ($self->{'reg_file'}) {
        $worker_cmd .= ' -regfile '. $self->{'reg_file'} .' -regname '. $self->{'reg_name'};
    } else {
        $worker_cmd .= ' -url '. $self->{'url'};
    }
337

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

sub run_autonomously {
Leo Gordon's avatar
Leo Gordon committed
342
    my ($self, $max_loops, $queen, $this_analysis) = @_;
343

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

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

Leo Gordon's avatar
Leo Gordon committed
351 352 353 354
        # pre-hash the resource_class xparams for future use:
    my %rc_xparams = map { ($_->rc_id => $_->parameters) }
        @{ $self->{'dba'}->get_ResourceDescriptionAdaptor->fetch_all_by_meadowtype($self->{'meadow'}->type()) };

Leo Gordon's avatar
Leo Gordon committed
355 356 357
    my $iteration=0;
    my $num_of_remaining_jobs=0;
    my $failed_analyses=0;
Leo Gordon's avatar
Leo Gordon committed
358
    my $order = $self->{'maximise_concurrency'}*2-1;
Leo Gordon's avatar
Leo Gordon committed
359 360 361 362 363 364
    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);  
365
        }
366

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

Leo Gordon's avatar
Leo Gordon committed
369
        $queen->check_for_dead_workers($self->{'meadow'}, 0);
370

Leo Gordon's avatar
Leo Gordon committed
371 372 373
        $queen->print_analysis_status unless($self->{'no_analysis_stats'});
        $queen->print_running_worker_status;
        #show_failed_workers($self, $queen);
374

Leo Gordon's avatar
Leo Gordon committed
375
        my ($worker_count, $rc_hash) = $queen->get_needed_workers_resync_if_necessary($self->{'meadow'}, $this_analysis);
376

Leo Gordon's avatar
Leo Gordon committed
377 378 379 380 381 382 383 384
            # apply various technical and self-imposed limits:
        my $worker_quota = $self->{'meadow'}->limit_workers($worker_count);

        if($worker_quota) {
            foreach my $rc_id (sort {$order*($rc_hash->{$a}<=>$rc_hash->{$b})} keys %$rc_hash) {
                my $this_rc_worker_count = ($worker_quota < $rc_hash->{$rc_id})
                    ? $worker_quota
                    : $rc_hash->{$rc_id};
385

Leo Gordon's avatar
Leo Gordon committed
386
                print "Submitting $this_rc_worker_count workers (rc_id=$rc_id) to ".$self->{'meadow'}->type()."\n";
387

388
                $self->{'meadow'}->submit_workers($iteration, $worker_cmd, $this_rc_worker_count, $rc_id, $rc_xparams{$rc_id} || '');
Leo Gordon's avatar
Leo Gordon committed
389 390

                $worker_quota -= $this_rc_worker_count;
Leo Gordon's avatar
Leo Gordon committed
391
            }
Leo Gordon's avatar
Leo Gordon committed
392 393 394
        } else {
            print "Not submitting any workers this iteration\n";
        }
395

Leo Gordon's avatar
Leo Gordon committed
396
        $failed_analyses       = $queen->get_num_failed_analyses($this_analysis);
Leo Gordon's avatar
Leo Gordon committed
397
        $num_of_remaining_jobs = $queen->get_remaining_jobs_show_hive_progress();
398

Leo Gordon's avatar
Leo Gordon committed
399
    } while(!$failed_analyses and $num_of_remaining_jobs and $iteration!=$max_loops);
400

Leo Gordon's avatar
Leo Gordon committed
401 402 403 404 405 406
    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
407
    printf("dbc %d disconnect cycles\n", $self->{'dba'}->dbc->disconnect_count);
408 409
}

410
sub reset_all_jobs_for_analysis {
Leo Gordon's avatar
Leo Gordon committed
411
    my ($self, $logic_name) = @_;
412
  
Leo Gordon's avatar
Leo Gordon committed
413
  my $analysis = $self->{'dba'}->get_AnalysisAdaptor->fetch_by_logic_name($logic_name)
414
      || die( "Cannot AnalysisAdaptor->fetch_by_logic_name($logic_name)"); 
415 416 417 418
  
  $self->{'dba'}->get_AnalysisJobAdaptor->reset_all_jobs_for_analysis_id($analysis->dbID); 
  $self->{'dba'}->get_Queen->synchronize_AnalysisStats($analysis->stats);
}
419 420

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

Leo Gordon's avatar
Leo Gordon committed
423 424 425 426 427 428
    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); 
429
}
Leo Gordon's avatar
Leo Gordon committed
430

431 432 433 434 435 436 437 438 439 440
__DATA__

=pod

=head1 NAME

    beekeeper.pl

=head1 DESCRIPTION

Leo Gordon's avatar
Leo Gordon committed
441 442 443
    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
444

Leo Gordon's avatar
Leo Gordon committed
445 446
    It is also responsible for interfacing with the Queen to identify workers which died
    unexpectantly so that she can free the dead workers and reclaim unfinished jobs.
447 448 449

=head1 USAGE EXAMPLES

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

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

Leo Gordon's avatar
Leo Gordon committed
456 457
        # 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
458

Leo Gordon's avatar
Leo Gordon committed
459 460
        # Run the pipeline in automatic mode (-loop), run all the workers locally (-local) and allow for 3 parallel workers (-local_cpus 3)
    beekeeper.pl -url mysql://username:secret@hostname:port/long_mult_test -local -local_cpus 3 -loop
461

Leo Gordon's avatar
Leo Gordon committed
462 463
        # 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
464

Leo Gordon's avatar
Leo Gordon committed
465 466
        # 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
467

Leo Gordon's avatar
Leo Gordon committed
468 469
        # 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
470

Leo Gordon's avatar
Leo Gordon committed
471 472
        # Do a cleanup: find and bury dead workers, reclaim their jobs
    beekeeper.pl -url mysql://username:secret@hostname:port/long_mult_test -dead
473 474 475 476 477

=head1 OPTIONS

=head2 Connection parameters

Leo Gordon's avatar
Leo Gordon committed
478 479 480 481 482 483 484 485
    -conf <path>           : config file describing db connection
    -regfile <path>        : path to a Registry configuration file
    -regname <string>      : species/alias name for the Hive DBAdaptor
    -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>
486
    [-database] <name>     : mysql database <name>
487 488 489

=head2 Looping control

Leo Gordon's avatar
Leo Gordon committed
490 491 492
    -loop                  : run autonomously, loops and sleeps
    -max_loops <num>       : perform max this # of loops in autonomous mode
    -run                   : run 1 iteration of automation loop
Leo Gordon's avatar
Leo Gordon committed
493
    -job_id <job_id>       : run 1 iteration for this job_id
Leo Gordon's avatar
Leo Gordon committed
494
    -sleep <num>           : when looping, sleep <num> minutes (default 2min)
495 496 497

=head2 Meadow control

Leo Gordon's avatar
Leo Gordon committed
498 499 500 501 502
    -local                    : run jobs on local CPU (fork)
    -local_cpus <num>         : max # workers to be running locally
    -wlimit <num>             : max # workers to create per loop
    -no_pend                  : don't adjust needed workers by pending workers
    -meadow_options <string>  : passes <string> to the Meadow submission command as <options> (formerly lsf_options)
503 504 505

=head2 Worker control

506
    -job_limit <num>            : #jobs to run before worker can die naturally
507
    -batch_size <num>           : #jobs a worker can claim at once
508
    -life_span <num>            : life_span limit for each worker
509 510 511 512
    -logic_name <string>        : restrict the pipeline stat/runs to this analysis logic_name
    -maximise_concurrency 1     : try to run more different analyses at the same time
    -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
513 514 515

=head2 Other commands/options

Leo Gordon's avatar
Leo Gordon committed
516 517 518 519 520 521 522 523 524
    -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
525

Leo Gordon's avatar
Leo Gordon committed
526 527
=head1 CONTACT

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

530 531
=cut