{"action":"created","comment":{"url":"https://api.github.com/repos/opentracing/opentracing-java/pulls/comments/50500776","id":50500776,"diff_hunk":"@@ -0,0 +1,66 @@\n+/**\n+ * Copyright 2016 The OpenTracing Authors\n+ *\n+ * Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except\n+ * in compliance with the License. You may obtain a copy of the License at\n+ *\n+ * http://www.apache.org/licenses/LICENSE-2.0\n+ *\n+ * Unless required by applicable law or agreed to in writing, software distributed under the License\n+ * is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express\n+ * or implied. See the License for the specific language governing permissions and limitations under\n+ * the License.\n+ */\n+package opentracing;\n+\n+/**\n+ * SpanContext encpasulates the smallest amount of state needed to describe a Span's identity\n+ * within a larger [potentially distributed] trace. The SpanContext is not intended to encode the\n+ * span's operation name, timing, or log data, but merely any unique identifiers (etc) needed to\n+ * contextualize it within a larger trace tree.\n+ *\n+ * <p>SpanContexts are sufficient to propagate the, well, *context* of a particular trace between\n+ * processes.\n+ *\n+ * <p>SpanContext also support a simple string map of \"trace attributes\". These trace attributes\n+ * are special in that they are propagated *in-band*, presumably alongside application data. See the\n+ * documentation for {@link #setAttribute(String, String)} for more details and some important\n+ * caveats.\n+ */\n+public interface SpanContext {\n+\n+  /**\n+   * Sets a tag on this SpanContext that also propagates to future children per {@link\n+   * TraceContextSource#newChild(TraceContext)}.\n+   *\n+   * <p>Trace attributes enables powerful functionality given a full-stack opentracing integration\n+   * (e.g., arbitrary application data from a mobile app can make it, transparently, all the way\n+   * into the depths of a storage system), and with it some powerful costs: use this feature with\n+   * care.\n+   *\n+   * <p>IMPORTANT NOTE #1: This will only propagate trace attributes to *future* children of the\n+   * TraceContextSource#newChild(TraceContext)} and/or the Span that references it.\n+   *\n+   * <p>IMPORTANT NOTE #2: Use this thoughtfully and with care. Every key and value is copied into\n+   * every local *and remote* child of this TraceContext, and that can add up to a lot of network\n+   * and cpu overhead.\n+   *\n+   * <p>IMPORTANT NOTE #3: Trace attributes keys have a restricted format: implementations may wish\n+   * to use them as HTTP header keys (or key suffixes), and of course HTTP headers are case\n+   * insensitive.\n+   *\n+   * @param restrictedKey MUST match the regular expression `(?i:[a-z0-9][-a-z0-9]*)` and is\n+   * case-insensitive. That is, it must start with a letter or number, and the remaining characters\n+   * must be letters, numbers, or hyphens. undefined behavior results if the `restrictedKey` does\n+   * not meet these criteria.\n+   */\n+  SpanContext setAttribute(String restrictedKey, String value);\n+\n+  /**\n+   * Gets the value for a trace tag given its key. Returns Null if the value isn't found in this\n+   * TraceContext.\n+   *\n+   * @param restrictedKey see {@link #setAttribute(String, String)} notes.\n+   */\n+  String getAttribute(String restrictedKey);","path":"opentracing/src/main/java/opentracing/SpanContext.java","position":65,"original_position":65,"commit_id":"5630ab2389e054f9a353b35642acb87eac5cd00c","original_commit_id":"5630ab2389e054f9a353b35642acb87eac5cd00c","user":{"login":"yurishkuro","id":3523016,"avatar_url":"https://avatars.githubusercontent.com/u/3523016?v=3","gravatar_id":"","url":"https://api.github.com/users/yurishkuro","html_url":"https://github.com/yurishkuro","followers_url":"https://api.github.com/users/yurishkuro/followers","following_url":"https://api.github.com/users/yurishkuro/following{/other_user}","gists_url":"https://api.github.com/users/yurishkuro/gists{/gist_id}","starred_url":"https://api.github.com/users/yurishkuro/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/yurishkuro/subscriptions","organizations_url":"https://api.github.com/users/yurishkuro/orgs","repos_url":"https://api.github.com/users/yurishkuro/repos","events_url":"https://api.github.com/users/yurishkuro/events{/privacy}","received_events_url":"https://api.github.com/users/yurishkuro/received_events","type":"User","site_admin":false},"body":"the whole point of trace attributes is to be accessible to application code at deeper levels of the call tree.","created_at":"2016-01-22T04:17:20Z","updated_at":"2016-01-22T04:17:20Z","html_url":"https://github.com/opentracing/opentracing-java/pull/7#discussion_r50500776","pull_request_url":"https://api.github.com/repos/opentracing/opentracing-java/pulls/7","_links":{"self":{"href":"https://api.github.com/repos/opentracing/opentracing-java/pulls/comments/50500776"},"html":{"href":"https://github.com/opentracing/opentracing-java/pull/7#discussion_r50500776"},"pull_request":{"href":"https://api.github.com/repos/opentracing/opentracing-java/pulls/7"}}},"pull_request":{"url":"https://api.github.com/repos/opentracing/opentracing-java/pulls/7","id":56839685,"html_url":"https://github.com/opentracing/opentracing-java/pull/7","diff_url":"https://github.com/opentracing/opentracing-java/pull/7.diff","patch_url":"https://github.com/opentracing/opentracing-java/pull/7.patch","issue_url":"https://api.github.com/repos/opentracing/opentracing-java/issues/7","number":7,"state":"open","locked":false,"title":"In discrete steps, Simplify the API","user":{"login":"michaelsembwever","id":559444,"avatar_url":"https://avatars.githubusercontent.com/u/559444?v=3","gravatar_id":"","url":"https://api.github.com/users/michaelsembwever","html_url":"https://github.com/michaelsembwever","followers_url":"https://api.github.com/users/michaelsembwever/followers","following_url":"https://api.github.com/users/michaelsembwever/following{/other_user}","gists_url":"https://api.github.com/users/michaelsembwever/gists{/gist_id}","starred_url":"https://api.github.com/users/michaelsembwever/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/michaelsembwever/subscriptions","organizations_url":"https://api.github.com/users/michaelsembwever/orgs","repos_url":"https://api.github.com/users/michaelsembwever/repos","events_url":"https://api.github.com/users/michaelsembwever/events{/privacy}","received_events_url":"https://api.github.com/users/michaelsembwever/received_events","type":"User","site_admin":false},"body":"This PR contains a sequence of commits to simplify the API.\r\n\r\nClass renames:\r\n - TraceContext to SpanContext\r\n - TraceContextSource to TraceContext\r\n - TraceContextCodec to TraceCodec\r\n\r\nRemoving porcelain api:\r\n - Span.createChild(..)\r\n - TraceContext.ChildSpanContext\r\n - logging methods in Span (replaced with `event(message, payload)`).\r\n\r\nLook in the individual commits for the rationale to each.\r\n\r\nIt's clearer to see the value of the changes by looking at the HEAD of the branch rather than evaluating the patch.","created_at":"2016-01-22T02:35:02Z","updated_at":"2016-01-22T04:17:20Z","closed_at":null,"merged_at":null,"merge_commit_sha":"44ece45271a7d321c55abbd2057a8445f55933f4","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/opentracing/opentracing-java/pulls/7/commits","review_comments_url":"https://api.github.com/repos/opentracing/opentracing-java/pulls/7/comments","review_comment_url":"https://api.github.com/repos/opentracing/opentracing-java/pulls/comments{/number}","comments_url":"https://api.github.com/repos/opentracing/opentracing-java/issues/7/comments","statuses_url":"https://api.github.com/repos/opentracing/opentracing-java/statuses/5630ab2389e054f9a353b35642acb87eac5cd00c","head":{"label":"opentracing:mck/simplified-api-design-0","ref":"mck/simplified-api-design-0","sha":"5630ab2389e054f9a353b35642acb87eac5cd00c","user":{"login":"opentracing","id":15482765,"avatar_url":"https://avatars.githubusercontent.com/u/15482765?v=3","gravatar_id":"","url":"https://api.github.com/users/opentracing","html_url":"https://github.com/opentracing","followers_url":"https://api.github.com/users/opentracing/followers","following_url":"https://api.github.com/users/opentracing/following{/other_user}","gists_url":"https://api.github.com/users/opentracing/gists{/gist_id}","starred_url":"https://api.github.com/users/opentracing/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/opentracing/subscriptions","organizations_url":"https://api.github.com/users/opentracing/orgs","repos_url":"https://api.github.com/users/opentracing/repos","events_url":"https://api.github.com/users/opentracing/events{/privacy}","received_events_url":"https://api.github.com/users/opentracing/received_events","type":"Organization","site_admin":false},"repo":{"id":48295629,"name":"opentracing-java","full_name":"opentracing/opentracing-java","owner":{"login":"opentracing","id":15482765,"avatar_url":"https://avatars.githubusercontent.com/u/15482765?v=3","gravatar_id":"","url":"https://api.github.com/users/opentracing","html_url":"https://github.com/opentracing","followers_url":"https://api.github.com/users/opentracing/followers","following_url":"https://api.github.com/users/opentracing/following{/other_user}","gists_url":"https://api.github.com/users/opentracing/gists{/gist_id}","starred_url":"https://api.github.com/users/opentracing/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/opentracing/subscriptions","organizations_url":"https://api.github.com/users/opentracing/orgs","repos_url":"https://api.github.com/users/opentracing/repos","events_url":"https://api.github.com/users/opentracing/events{/privacy}","received_events_url":"https://api.github.com/users/opentracing/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/opentracing/opentracing-java","description":"","fork":false,"url":"https://api.github.com/repos/opentracing/opentracing-java","forks_url":"https://api.github.com/repos/opentracing/opentracing-java/forks","keys_url":"https://api.github.com/repos/opentracing/opentracing-java/keys{/key_id}","collaborators_url":"https://api.github.com/repos/opentracing/opentracing-java/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/opentracing/opentracing-java/teams","hooks_url":"https://api.github.com/repos/opentracing/opentracing-java/hooks","issue_events_url":"https://api.github.com/repos/opentracing/opentracing-java/issues/events{/number}","events_url":"https://api.github.com/repos/opentracing/opentracing-java/events","assignees_url":"https://api.github.com/repos/opentracing/opentracing-java/assignees{/user}","branches_url":"https://api.github.com/repos/opentracing/opentracing-java/branches{/branch}","tags_url":"https://api.github.com/repos/opentracing/opentracing-java/tags","blobs_url":"https://api.github.com/repos/opentracing/opentracing-java/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/opentracing/opentracing-java/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/opentracing/opentracing-java/git/refs{/sha}","trees_url":"https://api.github.com/repos/opentracing/opentracing-java/git/trees{/sha}","statuses_url":"https://api.github.com/repos/opentracing/opentracing-java/statuses/{sha}","languages_url":"https://api.github.com/repos/opentracing/opentracing-java/languages","stargazers_url":"https://api.github.com/repos/opentracing/opentracing-java/stargazers","contributors_url":"https://api.github.com/repos/opentracing/opentracing-java/contributors","subscribers_url":"https://api.github.com/repos/opentracing/opentracing-java/subscribers","subscription_url":"https://api.github.com/repos/opentracing/opentracing-java/subscription","commits_url":"https://api.github.com/repos/opentracing/opentracing-java/commits{/sha}","git_commits_url":"https://api.github.com/repos/opentracing/opentracing-java/git/commits{/sha}","comments_url":"https://api.github.com/repos/opentracing/opentracing-java/comments{/number}","issue_comment_url":"https://api.github.com/repos/opentracing/opentracing-java/issues/comments{/number}","contents_url":"https://api.github.com/repos/opentracing/opentracing-java/contents/{+path}","compare_url":"https://api.github.com/repos/opentracing/opentracing-java/compare/{base}...{head}","merges_url":"https://api.github.com/repos/opentracing/opentracing-java/merges","archive_url":"https://api.github.com/repos/opentracing/opentracing-java/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/opentracing/opentracing-java/downloads","issues_url":"https://api.github.com/repos/opentracing/opentracing-java/issues{/number}","pulls_url":"https://api.github.com/repos/opentracing/opentracing-java/pulls{/number}","milestones_url":"https://api.github.com/repos/opentracing/opentracing-java/milestones{/number}","notifications_url":"https://api.github.com/repos/opentracing/opentracing-java/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/opentracing/opentracing-java/labels{/name}","releases_url":"https://api.github.com/repos/opentracing/opentracing-java/releases{/id}","deployments_url":"https://api.github.com/repos/opentracing/opentracing-java/deployments","created_at":"2015-12-19T20:07:30Z","updated_at":"2016-01-18T16:51:48Z","pushed_at":"2016-01-22T02:35:02Z","git_url":"git://github.com/opentracing/opentracing-java.git","ssh_url":"git@github.com:opentracing/opentracing-java.git","clone_url":"https://github.com/opentracing/opentracing-java.git","svn_url":"https://github.com/opentracing/opentracing-java","homepage":null,"size":92,"stargazers_count":4,"watchers_count":4,"language":"Shell","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":3,"mirror_url":null,"open_issues_count":3,"forks":3,"open_issues":3,"watchers":4,"default_branch":"master"}},"base":{"label":"opentracing:interfaces","ref":"interfaces","sha":"53fb14051cefa2ff77e66a3ec43f7d8886933269","user":{"login":"opentracing","id":15482765,"avatar_url":"https://avatars.githubusercontent.com/u/15482765?v=3","gravatar_id":"","url":"https://api.github.com/users/opentracing","html_url":"https://github.com/opentracing","followers_url":"https://api.github.com/users/opentracing/followers","following_url":"https://api.github.com/users/opentracing/following{/other_user}","gists_url":"https://api.github.com/users/opentracing/gists{/gist_id}","starred_url":"https://api.github.com/users/opentracing/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/opentracing/subscriptions","organizations_url":"https://api.github.com/users/opentracing/orgs","repos_url":"https://api.github.com/users/opentracing/repos","events_url":"https://api.github.com/users/opentracing/events{/privacy}","received_events_url":"https://api.github.com/users/opentracing/received_events","type":"Organization","site_admin":false},"repo":{"id":48295629,"name":"opentracing-java","full_name":"opentracing/opentracing-java","owner":{"login":"opentracing","id":15482765,"avatar_url":"https://avatars.githubusercontent.com/u/15482765?v=3","gravatar_id":"","url":"https://api.github.com/users/opentracing","html_url":"https://github.com/opentracing","followers_url":"https://api.github.com/users/opentracing/followers","following_url":"https://api.github.com/users/opentracing/following{/other_user}","gists_url":"https://api.github.com/users/opentracing/gists{/gist_id}","starred_url":"https://api.github.com/users/opentracing/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/opentracing/subscriptions","organizations_url":"https://api.github.com/users/opentracing/orgs","repos_url":"https://api.github.com/users/opentracing/repos","events_url":"https://api.github.com/users/opentracing/events{/privacy}","received_events_url":"https://api.github.com/users/opentracing/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/opentracing/opentracing-java","description":"","fork":false,"url":"https://api.github.com/repos/opentracing/opentracing-java","forks_url":"https://api.github.com/repos/opentracing/opentracing-java/forks","keys_url":"https://api.github.com/repos/opentracing/opentracing-java/keys{/key_id}","collaborators_url":"https://api.github.com/repos/opentracing/opentracing-java/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/opentracing/opentracing-java/teams","hooks_url":"https://api.github.com/repos/opentracing/opentracing-java/hooks","issue_events_url":"https://api.github.com/repos/opentracing/opentracing-java/issues/events{/number}","events_url":"https://api.github.com/repos/opentracing/opentracing-java/events","assignees_url":"https://api.github.com/repos/opentracing/opentracing-java/assignees{/user}","branches_url":"https://api.github.com/repos/opentracing/opentracing-java/branches{/branch}","tags_url":"https://api.github.com/repos/opentracing/opentracing-java/tags","blobs_url":"https://api.github.com/repos/opentracing/opentracing-java/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/opentracing/opentracing-java/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/opentracing/opentracing-java/git/refs{/sha}","trees_url":"https://api.github.com/repos/opentracing/opentracing-java/git/trees{/sha}","statuses_url":"https://api.github.com/repos/opentracing/opentracing-java/statuses/{sha}","languages_url":"https://api.github.com/repos/opentracing/opentracing-java/languages","stargazers_url":"https://api.github.com/repos/opentracing/opentracing-java/stargazers","contributors_url":"https://api.github.com/repos/opentracing/opentracing-java/contributors","subscribers_url":"https://api.github.com/repos/opentracing/opentracing-java/subscribers","subscription_url":"https://api.github.com/repos/opentracing/opentracing-java/subscription","commits_url":"https://api.github.com/repos/opentracing/opentracing-java/commits{/sha}","git_commits_url":"https://api.github.com/repos/opentracing/opentracing-java/git/commits{/sha}","comments_url":"https://api.github.com/repos/opentracing/opentracing-java/comments{/number}","issue_comment_url":"https://api.github.com/repos/opentracing/opentracing-java/issues/comments{/number}","contents_url":"https://api.github.com/repos/opentracing/opentracing-java/contents/{+path}","compare_url":"https://api.github.com/repos/opentracing/opentracing-java/compare/{base}...{head}","merges_url":"https://api.github.com/repos/opentracing/opentracing-java/merges","archive_url":"https://api.github.com/repos/opentracing/opentracing-java/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/opentracing/opentracing-java/downloads","issues_url":"https://api.github.com/repos/opentracing/opentracing-java/issues{/number}","pulls_url":"https://api.github.com/repos/opentracing/opentracing-java/pulls{/number}","milestones_url":"https://api.github.com/repos/opentracing/opentracing-java/milestones{/number}","notifications_url":"https://api.github.com/repos/opentracing/opentracing-java/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/opentracing/opentracing-java/labels{/name}","releases_url":"https://api.github.com/repos/opentracing/opentracing-java/releases{/id}","deployments_url":"https://api.github.com/repos/opentracing/opentracing-java/deployments","created_at":"2015-12-19T20:07:30Z","updated_at":"2016-01-18T16:51:48Z","pushed_at":"2016-01-22T02:35:02Z","git_url":"git://github.com/opentracing/opentracing-java.git","ssh_url":"git@github.com:opentracing/opentracing-java.git","clone_url":"https://github.com/opentracing/opentracing-java.git","svn_url":"https://github.com/opentracing/opentracing-java","homepage":null,"size":92,"stargazers_count":4,"watchers_count":4,"language":"Shell","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":3,"mirror_url":null,"open_issues_count":3,"forks":3,"open_issues":3,"watchers":4,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/opentracing/opentracing-java/pulls/7"},"html":{"href":"https://github.com/opentracing/opentracing-java/pull/7"},"issue":{"href":"https://api.github.com/repos/opentracing/opentracing-java/issues/7"},"comments":{"href":"https://api.github.com/repos/opentracing/opentracing-java/issues/7/comments"},"review_comments":{"href":"https://api.github.com/repos/opentracing/opentracing-java/pulls/7/comments"},"review_comment":{"href":"https://api.github.com/repos/opentracing/opentracing-java/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/opentracing/opentracing-java/pulls/7/commits"},"statuses":{"href":"https://api.github.com/repos/opentracing/opentracing-java/statuses/5630ab2389e054f9a353b35642acb87eac5cd00c"}}}}