{"action":"created","comment":{"url":"https://api.github.com/repos/twitter/finagle/pulls/comments/42940060","id":42940060,"diff_hunk":"@@ -22,25 +22,131 @@ namespace rb FinagleThrift\n  *   http://j.mp/fZZnyD\n  */\n \n-// these are the annotations we always expect to find in a span\n-const string WIRE_SEND = \"ws\"\n-const string WIRE_RECV = \"wr\"\n+#************** Annotation.value **************\n+/*\n+ * The client sent (\"cs\") a request to a server. There is only one send per\n+ * span. For example, if there's a transport error, each attempt can be logged\n+ * as a WIRE_SEND annotation.\n+ *\n+ * If chunking is involved, each chunk could be logged as a separate\n+ * CLIENT_SEND_FRAGMENT in the same span.\n+ *\n+ * Annotation.host is not the server. It is the host which logged the send\n+ * event, almost always the client.\n+ *\n+ * To record the actual endpoints of the client and server side of the span,\n+ * use CLIENT_ADDR and SERVER_ADDR respectively.\n+ */\n const string CLIENT_SEND = \"cs\"\n+/*\n+ * The client received (\"cr\") a response from a server. There is only one\n+ * receive per span. For example, if duplicate responses were received, each\n+ * can be logged as a WIRE_RECV annotation.\n+ *\n+ * If chunking is involved, each chunk could be logged as a separate\n+ * CLIENT_RECV_FRAGMENT in the same span.\n+ *\n+ * Annotation.host is not the server. It is the host which logged the receive\n+ * event, almost always the client.\n+ *\n+ * To record the actual endpoints of the client and server side of the span,\n+ * use CLIENT_ADDR and SERVER_ADDR respectively.\n+ */\n const string CLIENT_RECV = \"cr\"\n+/*\n+ * The server sent (\"ss\") a response to a client. There is only one response\n+ * per span. If there's a transport error, each attempt can be logged as a\n+ * WIRE_SEND annotation.\n+ *\n+ * Typically, a trace ends with a server send, so the last timestamp of a trace\n+ * is often the timestamp of the root span's server send.\n+ *\n+ * If chunking is involved, each chunk could be logged as a separate\n+ * SERVER_SEND_FRAGMENT in the same span.\n+ *\n+ * Annotation.host is not the client. It is the host which logged the send\n+ * event, almost always the server.\n+ *\n+ * To record the actual endpoints of the client and server side of the span,\n+ * use CLIENT_ADDR and SERVER_ADDR respectively.\n+ */\n const string SERVER_SEND = \"ss\"\n+/*\n+ * The server received (\"cr\") a request from a client. There is only one\n+ * request per span.  For example, if duplicate responses were received, each\n+ * can be logged as a WIRE_RECV annotation.\n+ *\n+ * Typically, a trace starts with a server receive, so the first timestamp of a\n+ * trace is often the timestamp of the root span's server receive.\n+ *\n+ * If chunking is involved, each chunk could be logged as a separate\n+ * SERVER_RECV_FRAGMENT in the same span.\n+ *\n+ * Annotation.host is not the client. It is the host which logged the send\n+ * event, almost always the server.\n+ *\n+ * To record the actual endpoints of the client and server side of the span,\n+ * use CLIENT_ADDR and SERVER_ADDR respectively.\n+ */\n const string SERVER_RECV = \"sr\"\n-const string SERVER_ADDR = \"sa\"\n-const string CLIENT_ADDR = \"ca\"\n+/*\n+ * Optionally logs an attempt to send a message on the wire. Multiple wire send\n+ * events could indicate network retries. A lag between client or server send\n+ * and wire send might indicate queing or processing delay.","path":"finagle-thrift/src/main/thrift/tracing.thrift","position":79,"original_position":79,"commit_id":"4feaa27c28025e660613da766c1d5ecb0d98f1ba","original_commit_id":"4feaa27c28025e660613da766c1d5ecb0d98f1ba","user":{"login":"mosesn","id":156562,"avatar_url":"https://avatars.githubusercontent.com/u/156562?v=3","gravatar_id":"","url":"https://api.github.com/users/mosesn","html_url":"https://github.com/mosesn","followers_url":"https://api.github.com/users/mosesn/followers","following_url":"https://api.github.com/users/mosesn/following{/other_user}","gists_url":"https://api.github.com/users/mosesn/gists{/gist_id}","starred_url":"https://api.github.com/users/mosesn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mosesn/subscriptions","organizations_url":"https://api.github.com/users/mosesn/orgs","repos_url":"https://api.github.com/users/mosesn/repos","events_url":"https://api.github.com/users/mosesn/events{/privacy}","received_events_url":"https://api.github.com/users/mosesn/received_events","type":"User","site_admin":false},"body":"should be queuing","created_at":"2015-10-25T01:51:31Z","updated_at":"2015-10-25T01:51:31Z","html_url":"https://github.com/twitter/finagle/pull/434#discussion_r42940060","pull_request_url":"https://api.github.com/repos/twitter/finagle/pulls/434","_links":{"self":{"href":"https://api.github.com/repos/twitter/finagle/pulls/comments/42940060"},"html":{"href":"https://github.com/twitter/finagle/pull/434#discussion_r42940060"},"pull_request":{"href":"https://api.github.com/repos/twitter/finagle/pulls/434"}}},"pull_request":{"url":"https://api.github.com/repos/twitter/finagle/pulls/434","id":48667866,"html_url":"https://github.com/twitter/finagle/pull/434","diff_url":"https://github.com/twitter/finagle/pull/434.diff","patch_url":"https://github.com/twitter/finagle/pull/434.patch","issue_url":"https://api.github.com/repos/twitter/finagle/issues/434","number":434,"state":"open","locked":false,"title":"Adds documentation to annotations as they are often misunderstood","user":{"login":"adriancole","id":64215,"avatar_url":"https://avatars.githubusercontent.com/u/64215?v=3","gravatar_id":"","url":"https://api.github.com/users/adriancole","html_url":"https://github.com/adriancole","followers_url":"https://api.github.com/users/adriancole/followers","following_url":"https://api.github.com/users/adriancole/following{/other_user}","gists_url":"https://api.github.com/users/adriancole/gists{/gist_id}","starred_url":"https://api.github.com/users/adriancole/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/adriancole/subscriptions","organizations_url":"https://api.github.com/users/adriancole/orgs","repos_url":"https://api.github.com/users/adriancole/repos","events_url":"https://api.github.com/users/adriancole/events{/privacy}","received_events_url":"https://api.github.com/users/adriancole/received_events","type":"User","site_admin":false},"body":"Instrumentation libraries almost always get some aspect of annotations\r\nwrong. This is an attempt to document them, so that folks have a better\r\nchance at creating portable implementations.\r\n\r\nThis is a copy of https://github.com/openzipkin/zipkin/pull/794","created_at":"2015-10-24T23:31:15Z","updated_at":"2015-10-25T01:51:31Z","closed_at":null,"merged_at":null,"merge_commit_sha":"b41f8b2210dae441ca3c9908f1d30d9f0bc69a2b","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/twitter/finagle/pulls/434/commits","review_comments_url":"https://api.github.com/repos/twitter/finagle/pulls/434/comments","review_comment_url":"https://api.github.com/repos/twitter/finagle/pulls/comments{/number}","comments_url":"https://api.github.com/repos/twitter/finagle/issues/434/comments","statuses_url":"https://api.github.com/repos/twitter/finagle/statuses/4feaa27c28025e660613da766c1d5ecb0d98f1ba","head":{"label":"adriancole:dump-my-brains","ref":"dump-my-brains","sha":"4feaa27c28025e660613da766c1d5ecb0d98f1ba","user":{"login":"adriancole","id":64215,"avatar_url":"https://avatars.githubusercontent.com/u/64215?v=3","gravatar_id":"","url":"https://api.github.com/users/adriancole","html_url":"https://github.com/adriancole","followers_url":"https://api.github.com/users/adriancole/followers","following_url":"https://api.github.com/users/adriancole/following{/other_user}","gists_url":"https://api.github.com/users/adriancole/gists{/gist_id}","starred_url":"https://api.github.com/users/adriancole/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/adriancole/subscriptions","organizations_url":"https://api.github.com/users/adriancole/orgs","repos_url":"https://api.github.com/users/adriancole/repos","events_url":"https://api.github.com/users/adriancole/events{/privacy}","received_events_url":"https://api.github.com/users/adriancole/received_events","type":"User","site_admin":false},"repo":{"id":12354806,"name":"finagle","full_name":"adriancole/finagle","owner":{"login":"adriancole","id":64215,"avatar_url":"https://avatars.githubusercontent.com/u/64215?v=3","gravatar_id":"","url":"https://api.github.com/users/adriancole","html_url":"https://github.com/adriancole","followers_url":"https://api.github.com/users/adriancole/followers","following_url":"https://api.github.com/users/adriancole/following{/other_user}","gists_url":"https://api.github.com/users/adriancole/gists{/gist_id}","starred_url":"https://api.github.com/users/adriancole/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/adriancole/subscriptions","organizations_url":"https://api.github.com/users/adriancole/orgs","repos_url":"https://api.github.com/users/adriancole/repos","events_url":"https://api.github.com/users/adriancole/events{/privacy}","received_events_url":"https://api.github.com/users/adriancole/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/adriancole/finagle","description":"A fault tolerant, protocol-agnostic RPC system","fork":true,"url":"https://api.github.com/repos/adriancole/finagle","forks_url":"https://api.github.com/repos/adriancole/finagle/forks","keys_url":"https://api.github.com/repos/adriancole/finagle/keys{/key_id}","collaborators_url":"https://api.github.com/repos/adriancole/finagle/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/adriancole/finagle/teams","hooks_url":"https://api.github.com/repos/adriancole/finagle/hooks","issue_events_url":"https://api.github.com/repos/adriancole/finagle/issues/events{/number}","events_url":"https://api.github.com/repos/adriancole/finagle/events","assignees_url":"https://api.github.com/repos/adriancole/finagle/assignees{/user}","branches_url":"https://api.github.com/repos/adriancole/finagle/branches{/branch}","tags_url":"https://api.github.com/repos/adriancole/finagle/tags","blobs_url":"https://api.github.com/repos/adriancole/finagle/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/adriancole/finagle/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/adriancole/finagle/git/refs{/sha}","trees_url":"https://api.github.com/repos/adriancole/finagle/git/trees{/sha}","statuses_url":"https://api.github.com/repos/adriancole/finagle/statuses/{sha}","languages_url":"https://api.github.com/repos/adriancole/finagle/languages","stargazers_url":"https://api.github.com/repos/adriancole/finagle/stargazers","contributors_url":"https://api.github.com/repos/adriancole/finagle/contributors","subscribers_url":"https://api.github.com/repos/adriancole/finagle/subscribers","subscription_url":"https://api.github.com/repos/adriancole/finagle/subscription","commits_url":"https://api.github.com/repos/adriancole/finagle/commits{/sha}","git_commits_url":"https://api.github.com/repos/adriancole/finagle/git/commits{/sha}","comments_url":"https://api.github.com/repos/adriancole/finagle/comments{/number}","issue_comment_url":"https://api.github.com/repos/adriancole/finagle/issues/comments{/number}","contents_url":"https://api.github.com/repos/adriancole/finagle/contents/{+path}","compare_url":"https://api.github.com/repos/adriancole/finagle/compare/{base}...{head}","merges_url":"https://api.github.com/repos/adriancole/finagle/merges","archive_url":"https://api.github.com/repos/adriancole/finagle/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/adriancole/finagle/downloads","issues_url":"https://api.github.com/repos/adriancole/finagle/issues{/number}","pulls_url":"https://api.github.com/repos/adriancole/finagle/pulls{/number}","milestones_url":"https://api.github.com/repos/adriancole/finagle/milestones{/number}","notifications_url":"https://api.github.com/repos/adriancole/finagle/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/adriancole/finagle/labels{/name}","releases_url":"https://api.github.com/repos/adriancole/finagle/releases{/id}","created_at":"2013-08-25T05:53:19Z","updated_at":"2015-09-20T17:53:31Z","pushed_at":"2015-10-24T23:38:51Z","git_url":"git://github.com/adriancole/finagle.git","ssh_url":"git@github.com:adriancole/finagle.git","clone_url":"https://github.com/adriancole/finagle.git","svn_url":"https://github.com/adriancole/finagle","homepage":"http://twitter.github.io/finagle","size":20334,"stargazers_count":0,"watchers_count":0,"language":"Scala","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":1,"mirror_url":null,"open_issues_count":0,"forks":1,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"twitter:develop","ref":"develop","sha":"e917f276bb3c9c17c67f1aa345eabe8355356565","user":{"login":"twitter","id":50278,"avatar_url":"https://avatars.githubusercontent.com/u/50278?v=3","gravatar_id":"","url":"https://api.github.com/users/twitter","html_url":"https://github.com/twitter","followers_url":"https://api.github.com/users/twitter/followers","following_url":"https://api.github.com/users/twitter/following{/other_user}","gists_url":"https://api.github.com/users/twitter/gists{/gist_id}","starred_url":"https://api.github.com/users/twitter/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/twitter/subscriptions","organizations_url":"https://api.github.com/users/twitter/orgs","repos_url":"https://api.github.com/users/twitter/repos","events_url":"https://api.github.com/users/twitter/events{/privacy}","received_events_url":"https://api.github.com/users/twitter/received_events","type":"Organization","site_admin":false},"repo":{"id":1007362,"name":"finagle","full_name":"twitter/finagle","owner":{"login":"twitter","id":50278,"avatar_url":"https://avatars.githubusercontent.com/u/50278?v=3","gravatar_id":"","url":"https://api.github.com/users/twitter","html_url":"https://github.com/twitter","followers_url":"https://api.github.com/users/twitter/followers","following_url":"https://api.github.com/users/twitter/following{/other_user}","gists_url":"https://api.github.com/users/twitter/gists{/gist_id}","starred_url":"https://api.github.com/users/twitter/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/twitter/subscriptions","organizations_url":"https://api.github.com/users/twitter/orgs","repos_url":"https://api.github.com/users/twitter/repos","events_url":"https://api.github.com/users/twitter/events{/privacy}","received_events_url":"https://api.github.com/users/twitter/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/twitter/finagle","description":"A fault tolerant, protocol-agnostic RPC system","fork":false,"url":"https://api.github.com/repos/twitter/finagle","forks_url":"https://api.github.com/repos/twitter/finagle/forks","keys_url":"https://api.github.com/repos/twitter/finagle/keys{/key_id}","collaborators_url":"https://api.github.com/repos/twitter/finagle/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/twitter/finagle/teams","hooks_url":"https://api.github.com/repos/twitter/finagle/hooks","issue_events_url":"https://api.github.com/repos/twitter/finagle/issues/events{/number}","events_url":"https://api.github.com/repos/twitter/finagle/events","assignees_url":"https://api.github.com/repos/twitter/finagle/assignees{/user}","branches_url":"https://api.github.com/repos/twitter/finagle/branches{/branch}","tags_url":"https://api.github.com/repos/twitter/finagle/tags","blobs_url":"https://api.github.com/repos/twitter/finagle/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/twitter/finagle/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/twitter/finagle/git/refs{/sha}","trees_url":"https://api.github.com/repos/twitter/finagle/git/trees{/sha}","statuses_url":"https://api.github.com/repos/twitter/finagle/statuses/{sha}","languages_url":"https://api.github.com/repos/twitter/finagle/languages","stargazers_url":"https://api.github.com/repos/twitter/finagle/stargazers","contributors_url":"https://api.github.com/repos/twitter/finagle/contributors","subscribers_url":"https://api.github.com/repos/twitter/finagle/subscribers","subscription_url":"https://api.github.com/repos/twitter/finagle/subscription","commits_url":"https://api.github.com/repos/twitter/finagle/commits{/sha}","git_commits_url":"https://api.github.com/repos/twitter/finagle/git/commits{/sha}","comments_url":"https://api.github.com/repos/twitter/finagle/comments{/number}","issue_comment_url":"https://api.github.com/repos/twitter/finagle/issues/comments{/number}","contents_url":"https://api.github.com/repos/twitter/finagle/contents/{+path}","compare_url":"https://api.github.com/repos/twitter/finagle/compare/{base}...{head}","merges_url":"https://api.github.com/repos/twitter/finagle/merges","archive_url":"https://api.github.com/repos/twitter/finagle/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/twitter/finagle/downloads","issues_url":"https://api.github.com/repos/twitter/finagle/issues{/number}","pulls_url":"https://api.github.com/repos/twitter/finagle/pulls{/number}","milestones_url":"https://api.github.com/repos/twitter/finagle/milestones{/number}","notifications_url":"https://api.github.com/repos/twitter/finagle/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/twitter/finagle/labels{/name}","releases_url":"https://api.github.com/repos/twitter/finagle/releases{/id}","created_at":"2010-10-19T22:10:09Z","updated_at":"2015-10-24T17:33:54Z","pushed_at":"2015-10-24T23:38:52Z","git_url":"git://github.com/twitter/finagle.git","ssh_url":"git@github.com:twitter/finagle.git","clone_url":"https://github.com/twitter/finagle.git","svn_url":"https://github.com/twitter/finagle","homepage":"http://twitter.github.io/finagle","size":38512,"stargazers_count":3912,"watchers_count":3912,"language":"Scala","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":true,"forks_count":757,"mirror_url":null,"open_issues_count":36,"forks":757,"open_issues":36,"watchers":3912,"default_branch":"develop"}},"_links":{"self":{"href":"https://api.github.com/repos/twitter/finagle/pulls/434"},"html":{"href":"https://github.com/twitter/finagle/pull/434"},"issue":{"href":"https://api.github.com/repos/twitter/finagle/issues/434"},"comments":{"href":"https://api.github.com/repos/twitter/finagle/issues/434/comments"},"review_comments":{"href":"https://api.github.com/repos/twitter/finagle/pulls/434/comments"},"review_comment":{"href":"https://api.github.com/repos/twitter/finagle/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/twitter/finagle/pulls/434/commits"},"statuses":{"href":"https://api.github.com/repos/twitter/finagle/statuses/4feaa27c28025e660613da766c1d5ecb0d98f1ba"}}}}