{"action":"created","comment":{"url":"https://api.github.com/repos/cylc/cylc/pulls/comments/33915210","id":33915210,"diff_hunk":"@@ -5821,25 +5871,41 @@ \\subsection{Suite And Task Event Handling}\n See also~\\ref{SuiteEventHandling} and~\\ref{TaskEventHandling}\n in the {\\em Suite.rc Reference}.\n \n-Cylc can call nominated event handlers when certain suite or task events\n-occur. This is intended to facilitate centralized alerting and automated\n-handling of critical events. Event handlers can send an email or an SMS,\n-call a pager, and so on; or intervene in the operation of their own\n-suite using cylc commands.  \\lstinline=cylc [hook] email-suite= and\n-\\lstinline=cylc [hook] email-task= are example event handlers packaged\n-with cylc.\n+Cylc can call nominated event handlers when certain suite or task events occur.\n+This is intended to facilitate centralized alerting and automated handling of\n+critical events. Event handlers can be used to send a message, call a pager,\n+and so on; or intervene in the operation of their own suite using cylc\n+commands.\n \n-Event handlers can be located in the suite bin directory, otherwise\n-it is up to you to ensure their location is in \\lstinline=$PATH=\n-(in the shell in which cylc runs, on the suite host).\n-\n-Task event handlers are passed the following arguments by the suite daemon:\n+To send an email, you can use the built-in setting\n+\\lstinline=[[[events]]]mail events= to specify a list of events when\n+notifications should be sent. E.g. to send an email on (submission) failed and\n+retry, you can do:\n \n+\\lstset{language=suiterc}\n \\begin{lstlisting}\n-<task-event-handler> EVENT SUITE TASKID MESSAGE\n+[runtime]\n+    [[foo]]\n+        retry delays = PT0S, PT30S\n+        script = test \"${CYLC_TASK_TRY_NUMBER}\" -eq 3\n+        [[[events]]]\n+            mail events = submission failed, submission retry, failed, retry","path":"doc/cug.tex","position":107,"original_position":103,"commit_id":"0981026e8c6546764db699c7c2ecb654a7072e29","original_commit_id":"c3626cc5781db7351ad1b079120e052e4d99a15d","user":{"login":"matthewrmshin","id":908613,"avatar_url":"https://avatars.githubusercontent.com/u/908613?v=3","gravatar_id":"","url":"https://api.github.com/users/matthewrmshin","html_url":"https://github.com/matthewrmshin","followers_url":"https://api.github.com/users/matthewrmshin/followers","following_url":"https://api.github.com/users/matthewrmshin/following{/other_user}","gists_url":"https://api.github.com/users/matthewrmshin/gists{/gist_id}","starred_url":"https://api.github.com/users/matthewrmshin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/matthewrmshin/subscriptions","organizations_url":"https://api.github.com/users/matthewrmshin/orgs","repos_url":"https://api.github.com/users/matthewrmshin/repos","events_url":"https://api.github.com/users/matthewrmshin/events{/privacy}","received_events_url":"https://api.github.com/users/matthewrmshin/received_events","type":"User","site_admin":false},"body":"No, it is task events only for the moment. We should extend this to suite events soon, but as a separate change.","created_at":"2015-07-06T08:46:59Z","updated_at":"2015-07-06T08:46:59Z","html_url":"https://github.com/cylc/cylc/pull/1503#discussion_r33915210","pull_request_url":"https://api.github.com/repos/cylc/cylc/pulls/1503","_links":{"self":{"href":"https://api.github.com/repos/cylc/cylc/pulls/comments/33915210"},"html":{"href":"https://github.com/cylc/cylc/pull/1503#discussion_r33915210"},"pull_request":{"href":"https://api.github.com/repos/cylc/cylc/pulls/1503"}}},"pull_request":{"url":"https://api.github.com/repos/cylc/cylc/pulls/1503","id":37801355,"html_url":"https://github.com/cylc/cylc/pull/1503","diff_url":"https://github.com/cylc/cylc/pull/1503.diff","patch_url":"https://github.com/cylc/cylc/pull/1503.patch","issue_url":"https://api.github.com/repos/cylc/cylc/issues/1503","number":1503,"state":"open","locked":false,"title":"Event handler enhancements","user":{"login":"matthewrmshin","id":908613,"avatar_url":"https://avatars.githubusercontent.com/u/908613?v=3","gravatar_id":"","url":"https://api.github.com/users/matthewrmshin","html_url":"https://github.com/matthewrmshin","followers_url":"https://api.github.com/users/matthewrmshin/followers","following_url":"https://api.github.com/users/matthewrmshin/following{/other_user}","gists_url":"https://api.github.com/users/matthewrmshin/gists{/gist_id}","starred_url":"https://api.github.com/users/matthewrmshin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/matthewrmshin/subscriptions","organizations_url":"https://api.github.com/users/matthewrmshin/orgs","repos_url":"https://api.github.com/users/matthewrmshin/repos","events_url":"https://api.github.com/users/matthewrmshin/events{/privacy}","received_events_url":"https://api.github.com/users/matthewrmshin/received_events","type":"User","site_admin":false},"body":"New and additional settings to `suite.rc`:\r\n* Configurable remote task job logs retrieval.\r\n* Configurable task event email.\r\n* General task event handlers.\r\n* Task event handler can now be script templates.\r\n* Event handlers can now retry on failure.\r\n\r\nImprove diagnostics to `job-activity.log`.\r\n* Report command and return code as well as out and err of subprocess activities.\r\n* Clearer labels for activities.\r\n\r\nSuite run time database, new `task_job_logs` table:\r\n* Store location, size and modified time of the job logs.\r\n* (Location column can be updated by our anticipated future job log housekeeping functionality.)\r\n* It is an improved version of what is currently updated by `rose suite-hook` `rose_prune` and `rose suite-log --update`, and viewed by Rose Bush.\r\n\r\nOther re-factor and tidy up:\r\n* Store submit/run and event handler (re)try info in context objects.\r\n* Store the context and result of a shell command (for invoking under `cylc.mp_pool`) in a single object.\r\n  * All information in one place.\r\n  * Easy to log.\r\n  * Easy to retry command.\r\n* Use table name constants for task proxy DB inserts/updates.\r\n\r\nThis closes #181, addresses bullet points 1 to 3 of #992, and begins the 1st step for #1052.","created_at":"2015-06-16T14:34:02Z","updated_at":"2015-07-06T08:46:59Z","closed_at":null,"merged_at":null,"merge_commit_sha":"65652bfd3dac4d4cb546f5965c68a86e638031b9","assignee":{"login":"arjclark","id":2562650,"avatar_url":"https://avatars.githubusercontent.com/u/2562650?v=3","gravatar_id":"","url":"https://api.github.com/users/arjclark","html_url":"https://github.com/arjclark","followers_url":"https://api.github.com/users/arjclark/followers","following_url":"https://api.github.com/users/arjclark/following{/other_user}","gists_url":"https://api.github.com/users/arjclark/gists{/gist_id}","starred_url":"https://api.github.com/users/arjclark/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/arjclark/subscriptions","organizations_url":"https://api.github.com/users/arjclark/orgs","repos_url":"https://api.github.com/users/arjclark/repos","events_url":"https://api.github.com/users/arjclark/events{/privacy}","received_events_url":"https://api.github.com/users/arjclark/received_events","type":"User","site_admin":false},"milestone":{"url":"https://api.github.com/repos/cylc/cylc/milestones/5","html_url":"https://github.com/cylc/cylc/milestones/soon","labels_url":"https://api.github.com/repos/cylc/cylc/milestones/5/labels","id":262614,"number":5,"title":"soon","description":"A few months in the future. Top priority issues and easy fixes should initially be marked against this milestone, and then moved to *next-release* if work progresses quickly enough.","creator":{"login":"hjoliver","id":2362137,"avatar_url":"https://avatars.githubusercontent.com/u/2362137?v=3","gravatar_id":"","url":"https://api.github.com/users/hjoliver","html_url":"https://github.com/hjoliver","followers_url":"https://api.github.com/users/hjoliver/followers","following_url":"https://api.github.com/users/hjoliver/following{/other_user}","gists_url":"https://api.github.com/users/hjoliver/gists{/gist_id}","starred_url":"https://api.github.com/users/hjoliver/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hjoliver/subscriptions","organizations_url":"https://api.github.com/users/hjoliver/orgs","repos_url":"https://api.github.com/users/hjoliver/repos","events_url":"https://api.github.com/users/hjoliver/events{/privacy}","received_events_url":"https://api.github.com/users/hjoliver/received_events","type":"User","site_admin":false},"open_issues":69,"closed_issues":0,"state":"open","created_at":"2013-02-08T07:07:13Z","updated_at":"2015-07-03T11:04:29Z","due_on":"2015-08-30T23:00:00Z","closed_at":null},"commits_url":"https://api.github.com/repos/cylc/cylc/pulls/1503/commits","review_comments_url":"https://api.github.com/repos/cylc/cylc/pulls/1503/comments","review_comment_url":"https://api.github.com/repos/cylc/cylc/pulls/comments{/number}","comments_url":"https://api.github.com/repos/cylc/cylc/issues/1503/comments","statuses_url":"https://api.github.com/repos/cylc/cylc/statuses/0981026e8c6546764db699c7c2ecb654a7072e29","head":{"label":"matthewrmshin:hook","ref":"hook","sha":"0981026e8c6546764db699c7c2ecb654a7072e29","user":{"login":"matthewrmshin","id":908613,"avatar_url":"https://avatars.githubusercontent.com/u/908613?v=3","gravatar_id":"","url":"https://api.github.com/users/matthewrmshin","html_url":"https://github.com/matthewrmshin","followers_url":"https://api.github.com/users/matthewrmshin/followers","following_url":"https://api.github.com/users/matthewrmshin/following{/other_user}","gists_url":"https://api.github.com/users/matthewrmshin/gists{/gist_id}","starred_url":"https://api.github.com/users/matthewrmshin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/matthewrmshin/subscriptions","organizations_url":"https://api.github.com/users/matthewrmshin/orgs","repos_url":"https://api.github.com/users/matthewrmshin/repos","events_url":"https://api.github.com/users/matthewrmshin/events{/privacy}","received_events_url":"https://api.github.com/users/matthewrmshin/received_events","type":"User","site_admin":false},"repo":{"id":4710539,"name":"cylc","full_name":"matthewrmshin/cylc","owner":{"login":"matthewrmshin","id":908613,"avatar_url":"https://avatars.githubusercontent.com/u/908613?v=3","gravatar_id":"","url":"https://api.github.com/users/matthewrmshin","html_url":"https://github.com/matthewrmshin","followers_url":"https://api.github.com/users/matthewrmshin/followers","following_url":"https://api.github.com/users/matthewrmshin/following{/other_user}","gists_url":"https://api.github.com/users/matthewrmshin/gists{/gist_id}","starred_url":"https://api.github.com/users/matthewrmshin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/matthewrmshin/subscriptions","organizations_url":"https://api.github.com/users/matthewrmshin/orgs","repos_url":"https://api.github.com/users/matthewrmshin/repos","events_url":"https://api.github.com/users/matthewrmshin/events{/privacy}","received_events_url":"https://api.github.com/users/matthewrmshin/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/matthewrmshin/cylc","description":"Cylc: an engine for running meteorological suites","fork":true,"url":"https://api.github.com/repos/matthewrmshin/cylc","forks_url":"https://api.github.com/repos/matthewrmshin/cylc/forks","keys_url":"https://api.github.com/repos/matthewrmshin/cylc/keys{/key_id}","collaborators_url":"https://api.github.com/repos/matthewrmshin/cylc/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/matthewrmshin/cylc/teams","hooks_url":"https://api.github.com/repos/matthewrmshin/cylc/hooks","issue_events_url":"https://api.github.com/repos/matthewrmshin/cylc/issues/events{/number}","events_url":"https://api.github.com/repos/matthewrmshin/cylc/events","assignees_url":"https://api.github.com/repos/matthewrmshin/cylc/assignees{/user}","branches_url":"https://api.github.com/repos/matthewrmshin/cylc/branches{/branch}","tags_url":"https://api.github.com/repos/matthewrmshin/cylc/tags","blobs_url":"https://api.github.com/repos/matthewrmshin/cylc/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/matthewrmshin/cylc/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/matthewrmshin/cylc/git/refs{/sha}","trees_url":"https://api.github.com/repos/matthewrmshin/cylc/git/trees{/sha}","statuses_url":"https://api.github.com/repos/matthewrmshin/cylc/statuses/{sha}","languages_url":"https://api.github.com/repos/matthewrmshin/cylc/languages","stargazers_url":"https://api.github.com/repos/matthewrmshin/cylc/stargazers","contributors_url":"https://api.github.com/repos/matthewrmshin/cylc/contributors","subscribers_url":"https://api.github.com/repos/matthewrmshin/cylc/subscribers","subscription_url":"https://api.github.com/repos/matthewrmshin/cylc/subscription","commits_url":"https://api.github.com/repos/matthewrmshin/cylc/commits{/sha}","git_commits_url":"https://api.github.com/repos/matthewrmshin/cylc/git/commits{/sha}","comments_url":"https://api.github.com/repos/matthewrmshin/cylc/comments{/number}","issue_comment_url":"https://api.github.com/repos/matthewrmshin/cylc/issues/comments{/number}","contents_url":"https://api.github.com/repos/matthewrmshin/cylc/contents/{+path}","compare_url":"https://api.github.com/repos/matthewrmshin/cylc/compare/{base}...{head}","merges_url":"https://api.github.com/repos/matthewrmshin/cylc/merges","archive_url":"https://api.github.com/repos/matthewrmshin/cylc/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/matthewrmshin/cylc/downloads","issues_url":"https://api.github.com/repos/matthewrmshin/cylc/issues{/number}","pulls_url":"https://api.github.com/repos/matthewrmshin/cylc/pulls{/number}","milestones_url":"https://api.github.com/repos/matthewrmshin/cylc/milestones{/number}","notifications_url":"https://api.github.com/repos/matthewrmshin/cylc/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/matthewrmshin/cylc/labels{/name}","releases_url":"https://api.github.com/repos/matthewrmshin/cylc/releases{/id}","created_at":"2012-06-19T07:07:09Z","updated_at":"2015-05-08T11:59:22Z","pushed_at":"2015-07-03T15:51:11Z","git_url":"git://github.com/matthewrmshin/cylc.git","ssh_url":"git@github.com:matthewrmshin/cylc.git","clone_url":"https://github.com/matthewrmshin/cylc.git","svn_url":"https://github.com/matthewrmshin/cylc","homepage":"http://cylc.github.io/cylc/","size":72806,"stargazers_count":2,"watchers_count":2,"language":"Python","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":2,"default_branch":"master"}},"base":{"label":"cylc:master","ref":"master","sha":"be23a4a9f4b0f7fb65362e1e7bae6d284b415c8d","user":{"login":"cylc","id":824878,"avatar_url":"https://avatars.githubusercontent.com/u/824878?v=3","gravatar_id":"","url":"https://api.github.com/users/cylc","html_url":"https://github.com/cylc","followers_url":"https://api.github.com/users/cylc/followers","following_url":"https://api.github.com/users/cylc/following{/other_user}","gists_url":"https://api.github.com/users/cylc/gists{/gist_id}","starred_url":"https://api.github.com/users/cylc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cylc/subscriptions","organizations_url":"https://api.github.com/users/cylc/orgs","repos_url":"https://api.github.com/users/cylc/repos","events_url":"https://api.github.com/users/cylc/events{/privacy}","received_events_url":"https://api.github.com/users/cylc/received_events","type":"Organization","site_admin":false},"repo":{"id":1836229,"name":"cylc","full_name":"cylc/cylc","owner":{"login":"cylc","id":824878,"avatar_url":"https://avatars.githubusercontent.com/u/824878?v=3","gravatar_id":"","url":"https://api.github.com/users/cylc","html_url":"https://github.com/cylc","followers_url":"https://api.github.com/users/cylc/followers","following_url":"https://api.github.com/users/cylc/following{/other_user}","gists_url":"https://api.github.com/users/cylc/gists{/gist_id}","starred_url":"https://api.github.com/users/cylc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cylc/subscriptions","organizations_url":"https://api.github.com/users/cylc/orgs","repos_url":"https://api.github.com/users/cylc/repos","events_url":"https://api.github.com/users/cylc/events{/privacy}","received_events_url":"https://api.github.com/users/cylc/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/cylc/cylc","description":"This is the official repository of the cylc suite engine. It will normally contain just the master branch, with completed features merged in from feature branches in developer forks.","fork":false,"url":"https://api.github.com/repos/cylc/cylc","forks_url":"https://api.github.com/repos/cylc/cylc/forks","keys_url":"https://api.github.com/repos/cylc/cylc/keys{/key_id}","collaborators_url":"https://api.github.com/repos/cylc/cylc/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/cylc/cylc/teams","hooks_url":"https://api.github.com/repos/cylc/cylc/hooks","issue_events_url":"https://api.github.com/repos/cylc/cylc/issues/events{/number}","events_url":"https://api.github.com/repos/cylc/cylc/events","assignees_url":"https://api.github.com/repos/cylc/cylc/assignees{/user}","branches_url":"https://api.github.com/repos/cylc/cylc/branches{/branch}","tags_url":"https://api.github.com/repos/cylc/cylc/tags","blobs_url":"https://api.github.com/repos/cylc/cylc/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/cylc/cylc/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/cylc/cylc/git/refs{/sha}","trees_url":"https://api.github.com/repos/cylc/cylc/git/trees{/sha}","statuses_url":"https://api.github.com/repos/cylc/cylc/statuses/{sha}","languages_url":"https://api.github.com/repos/cylc/cylc/languages","stargazers_url":"https://api.github.com/repos/cylc/cylc/stargazers","contributors_url":"https://api.github.com/repos/cylc/cylc/contributors","subscribers_url":"https://api.github.com/repos/cylc/cylc/subscribers","subscription_url":"https://api.github.com/repos/cylc/cylc/subscription","commits_url":"https://api.github.com/repos/cylc/cylc/commits{/sha}","git_commits_url":"https://api.github.com/repos/cylc/cylc/git/commits{/sha}","comments_url":"https://api.github.com/repos/cylc/cylc/comments{/number}","issue_comment_url":"https://api.github.com/repos/cylc/cylc/issues/comments{/number}","contents_url":"https://api.github.com/repos/cylc/cylc/contents/{+path}","compare_url":"https://api.github.com/repos/cylc/cylc/compare/{base}...{head}","merges_url":"https://api.github.com/repos/cylc/cylc/merges","archive_url":"https://api.github.com/repos/cylc/cylc/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/cylc/cylc/downloads","issues_url":"https://api.github.com/repos/cylc/cylc/issues{/number}","pulls_url":"https://api.github.com/repos/cylc/cylc/pulls{/number}","milestones_url":"https://api.github.com/repos/cylc/cylc/milestones{/number}","notifications_url":"https://api.github.com/repos/cylc/cylc/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/cylc/cylc/labels{/name}","releases_url":"https://api.github.com/repos/cylc/cylc/releases{/id}","created_at":"2011-06-02T08:31:49Z","updated_at":"2015-06-09T12:30:14Z","pushed_at":"2015-07-03T15:51:12Z","git_url":"git://github.com/cylc/cylc.git","ssh_url":"git@github.com:cylc/cylc.git","clone_url":"https://github.com/cylc/cylc.git","svn_url":"https://github.com/cylc/cylc","homepage":"http://cylc.github.com/cylc","size":95605,"stargazers_count":27,"watchers_count":27,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":17,"mirror_url":null,"open_issues_count":167,"forks":17,"open_issues":167,"watchers":27,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/cylc/cylc/pulls/1503"},"html":{"href":"https://github.com/cylc/cylc/pull/1503"},"issue":{"href":"https://api.github.com/repos/cylc/cylc/issues/1503"},"comments":{"href":"https://api.github.com/repos/cylc/cylc/issues/1503/comments"},"review_comments":{"href":"https://api.github.com/repos/cylc/cylc/pulls/1503/comments"},"review_comment":{"href":"https://api.github.com/repos/cylc/cylc/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/cylc/cylc/pulls/1503/commits"},"statuses":{"href":"https://api.github.com/repos/cylc/cylc/statuses/0981026e8c6546764db699c7c2ecb654a7072e29"}}}}