github.com/munnerz/test-infra@v0.0.0-20190108210205-ce3d181dc989/prow/cmd/crier/README.md (about)

     1  # Crier
     2  
     3  Crier reports your prowjobs on their status changes.
     4  
     5  ## Usage / How to enable existing available reporters
     6  
     7  ### [Gerrit reporter](/prow/gerrit/reporter)
     8  
     9  You can enable gerrit reporter in crier by specifying `--gerrit` flag.
    10  
    11  Similar to the [gerrit adapter](/prow/cmd/gerrit), you'll need to specify `--gerrit-projects` for
    12  your gerrit projects, and also `--cookiefile` for the gerrit auth token (leave it unset for anonymous).
    13  
    14  Gerrit reporter will send a gerrit code review, when all [gerrit adapter](/prow/cmd/gerrit)
    15  scheduled prowjob finishes on a revision, aka, on `SuccessState`, `FailureState`, `AbortedState` or `ErrorState`.
    16  It will also attach a report url so people can find logs of the job.
    17  
    18  ### [Pubsub reporter](/prow/pubsub/reporter)
    19  
    20  You can enable pubsub reporter in crier by specifying `--pubsub` flag.
    21  
    22  You need to specify following labels in order for pubsub reporter to report your prowjob:
    23  
    24  | Label                          | Description                                                                                                                               |
    25  | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------|
    26  | `"prow.k8s.io/pubsub-project"` | Your gcp project where pubsub channel lives                                                                                               |
    27  | `"prow.k8s.io/pubsub-topic"`   | The [topic](https://cloud.google.com/pubsub/docs/publisher) of your pubsub message                                                        |
    28  | `"prow.k8s.io/pubsub-runID"`   | A user assigned job id. It's tied to the prowjob, serves as a name tag and help user to differentiate results in multiple pubsub messages |
    29  
    30  Pubsub reporter will report whenever prowjob has a state transition.
    31  
    32  You can check the reported result by [list the pubsub topic](https://cloud.google.com/sdk/gcloud/reference/pubsub/topics/list). 
    33  
    34  <!-- TODO(krzyzacy): move github reporter over -->
    35  
    36  ## Implementation details
    37  
    38  Crier supports multiple reporters, each reporter will become a crier controller. Controllers
    39  will get prowjob change notifications from a [shared informer](https://github.com/kubernetes/client-go/blob/master/tools/cache/shared_informer.go), and you can specify `--num-workers` to change parallelism.
    40  
    41  If you are interested in how client-go works under the hood, the details are explained 
    42  [in this doc](https://github.com/kubernetes/sample-controller/blob/master/docs/controller-client-go.md)
    43  
    44  
    45  ## Adding a new reporter
    46  
    47  Each crier controller takes in a reporter.
    48  
    49  Each reporter will implement the following interface:
    50  ```go
    51  type reportClient interface {
    52  	Report(pj *v1.ProwJob) error
    53  	GetName() string
    54  	ShouldReport(pj *v1.ProwJob) bool
    55  }
    56  ```
    57  
    58  `GetName` will return the name of your reporter, the name will be used as a key when we store previous
    59  reported state for each prowjob.
    60  
    61  `ShouldReport` will return if a prowjob should be handled by current reporter.
    62  
    63  `Report` is the actual report logic happens. Return `nil` means report is successful, and the reported
    64  state will be saved in the prowjob. Return an actual error if report fails, crier will re-add the prowjob
    65  key to the shared cache and retry up to 5 times.
    66  
    67  You can add a reporter that implements the above interface, and add a flag to turn it on/off in crier.
    68