{"action":"created","comment":{"url":"https://api.github.com/repos/opentracing/opentracing.io/pulls/comments/198430172","pull_request_review_id":132349237,"id":198430172,"node_id":"MDI0OlB1bGxSZXF1ZXN0UmV2aWV3Q29tbWVudDE5ODQzMDE3Mg==","diff_hunk":"@@ -2,8 +2,142 @@\n title: \"Java: Inject and Extract\"\n ---\n \n-* When do you use Inject and Extract?\n-* Carriers and Format Options\n-* Injecting and Extracting HTTP\n-* Injecting and Extracting TextMap\n-* Injecting and Extracting Binary\n+## Introduction\n+\n+In order to trace across process boundaries and RPC calls in distributed systems, span context needs to propagated over the wire. The Java Opentracing API provides two functions in the Tracer interface to do just that, `inject(SpanContext, format, carrier)` and `extract(format, carrier)`.\n+\n+## Format Options and Carriers\n+The **format** parameter refers to one of the three standard encodings the OpenTracing API defines:\n+\n+1. `TEXT_MAP` where span context is encoded as a collection of string key-value pairs,\n+2. `BINARY` where span context is encoded as an opaque byte array,\n+3. `HTTP_HEADERS`, which is similar to `TEXT_MAP` except that the keys must be safe to be used as HTTP headers.\n+\n+The **carrier** is an abstraction over the underlying RPC framework. For example, a carrier for `TEXT_MAP` format is an interface that allows the tracer to write key-value pairs via `put(key, value)` method, while a carrier for Binary format is simply a ByteBuffer.\n+\n+## Injecting and Extracting HTTP\n+The following section discusses injecting and extracting a span's context over HTTP requests.\n+#### Injecting the Span’s Context to HTTP\n+In order to pass a span’s context over the HTTP request, the developer needs to call the `tracer.inject` before building the HTTP request, like so:\n+\n+```java\n+Tags.SPAN_KIND.set(tracer.activeSpan(), Tags.SPAN_KIND_CLIENT);\n+Tags.HTTP_METHOD.set(tracer.activeSpan(), \"GET\");\n+Tags.HTTP_URL.set(tracer.activeSpan(), url.toString());\n+tracer.inject(tracer.activeSpan().context(), Format.Builtin.HTTP_HEADERS, new RequestBuilderCarrier(requestBuilder));\n+```\n+Notice that a couple additional tags have been added to the `span` with some metadata about the HTTP request, following the OpenTracing Semantic Conventions.\n+In this case the `carrier` is HTTP request headers object, which can be adapted to the carrier API by wrapping it in a helper class as follows:\n+```java\n+public class RequestBuilderCarrier implements io.opentracing.propagation.TextMap {\n+    private final Request.Builder builder;\n+\n+    RequestBuilderCarrier(Request.Builder builder) {\n+        this.builder = builder;\n+    }\n+\n+    @Override\n+    public Iterator<Map.Entry<String, String>> iterator() {\n+        throw new UnsupportedOperationException(\"carrier is write-only\");\n+    }\n+\n+    @Override\n+    public void put(String key, String value) {\n+        builder.addHeader(key, value);\n+    }\n+}\n+```\n+#### Extracting the Span’s Context from Incoming Request\n+\n+The logic on the client side instrumentation is similar, the only difference is that `tracer.extract` is used and the span is tagged as `span.kind=server`.\n+\n+```java\n+public static Scope startServerSpan(Tracer tracer, javax.ws.rs.core.HttpHeaders httpHeaders,\n+        String operationName) {\n+    // format the headers for extraction\n+    MultivaluedMap<String, String> rawHeaders = httpHeaders.getRequestHeaders();\n+    final HashMap<String, String> headers = new HashMap<String, String>();\n+    for (String key : rawHeaders.keySet()) {\n+        headers.put(key, rawHeaders.get(key).get(0));\n+    }\n+\n+    Tracer.SpanBuilder spanBuilder;\n+    try {\n+        SpanContext parentSpan = tracer.extract(Format.Builtin.HTTP_HEADERS, new TextMapExtractAdapter(headers));\n+        if (parentSpan == null) {\n+            spanBuilder = tracer.buildSpan(operationName);\n+        } else {\n+            spanBuilder = tracer.buildSpan(operationName).asChildOf(parentSpan);\n+        }\n+    } catch (IllegalArgumentException e) {\n+        spanBuilder = tracer.buildSpan(operationName);\n+    }\n+    return spanBuilder.withTag(Tags.SPAN_KIND.getKey(), Tags.SPAN_KIND_SERVER).startActive(true);\n+}\n+```\n+\n+In the above example, instead of using a dedicated adapter class to convert JAXRS `HttpHeaders` type into `io.opentracing.propagation.TextMap`, the headers are copied to a plain `HashMap<String, String>` and converted using a standard adapter `TextMapExtractAdapter`.\n+\n+## Injecting and Extracting TextMap\n+The process of injecting and extracting `TextMap` is similar to that of HTTP. Given below are some elaborated code examples of injecting and extracting tracing information using `TextMap` format.\n+\n+```","path":"content/guides/java/inject-extract.md","position":88,"original_position":88,"commit_id":"9848c9f3f6aea2e3f8fe8a5b43fe728c372fc6a1","original_commit_id":"9848c9f3f6aea2e3f8fe8a5b43fe728c372fc6a1","user":{"login":"jpkrohling","id":13387,"node_id":"MDQ6VXNlcjEzMzg3","avatar_url":"https://avatars2.githubusercontent.com/u/13387?v=4","gravatar_id":"","url":"https://api.github.com/users/jpkrohling","html_url":"https://github.com/jpkrohling","followers_url":"https://api.github.com/users/jpkrohling/followers","following_url":"https://api.github.com/users/jpkrohling/following{/other_user}","gists_url":"https://api.github.com/users/jpkrohling/gists{/gist_id}","starred_url":"https://api.github.com/users/jpkrohling/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jpkrohling/subscriptions","organizations_url":"https://api.github.com/users/jpkrohling/orgs","repos_url":"https://api.github.com/users/jpkrohling/repos","events_url":"https://api.github.com/users/jpkrohling/events{/privacy}","received_events_url":"https://api.github.com/users/jpkrohling/received_events","type":"User","site_admin":false},"body":"And the same as a comment I left before: add a link to a real example on some repository.","created_at":"2018-06-27T09:40:46Z","updated_at":"2018-06-27T09:46:10Z","html_url":"https://github.com/opentracing/opentracing.io/pull/316#discussion_r198430172","pull_request_url":"https://api.github.com/repos/opentracing/opentracing.io/pulls/316","author_association":"CONTRIBUTOR","_links":{"self":{"href":"https://api.github.com/repos/opentracing/opentracing.io/pulls/comments/198430172"},"html":{"href":"https://github.com/opentracing/opentracing.io/pull/316#discussion_r198430172"},"pull_request":{"href":"https://api.github.com/repos/opentracing/opentracing.io/pulls/316"}},"in_reply_to_id":198429859},"pull_request":{"url":"https://api.github.com/repos/opentracing/opentracing.io/pulls/316","id":196995962,"node_id":"MDExOlB1bGxSZXF1ZXN0MTk2OTk1OTYy","html_url":"https://github.com/opentracing/opentracing.io/pull/316","diff_url":"https://github.com/opentracing/opentracing.io/pull/316.diff","patch_url":"https://github.com/opentracing/opentracing.io/pull/316.patch","issue_url":"https://api.github.com/repos/opentracing/opentracing.io/issues/316","number":316,"state":"open","locked":false,"title":"Add Java:Inject and Extract docs","user":{"login":"PikBot","id":35295607,"node_id":"MDQ6VXNlcjM1Mjk1NjA3","avatar_url":"https://avatars2.githubusercontent.com/u/35295607?v=4","gravatar_id":"","url":"https://api.github.com/users/PikBot","html_url":"https://github.com/PikBot","followers_url":"https://api.github.com/users/PikBot/followers","following_url":"https://api.github.com/users/PikBot/following{/other_user}","gists_url":"https://api.github.com/users/PikBot/gists{/gist_id}","starred_url":"https://api.github.com/users/PikBot/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/PikBot/subscriptions","organizations_url":"https://api.github.com/users/PikBot/orgs","repos_url":"https://api.github.com/users/PikBot/repos","events_url":"https://api.github.com/users/PikBot/events{/privacy}","received_events_url":"https://api.github.com/users/PikBot/received_events","type":"User","site_admin":false},"body":"Signed-off-by: Prakriti <prakritibansal98@gmail.com>\r\n\r\nrefs #282 ","created_at":"2018-06-25T03:56:23Z","updated_at":"2018-06-27T09:46:10Z","closed_at":null,"merged_at":null,"merge_commit_sha":"b14a8aa3ccc359c689c77f886594b7acfa0f7cec","assignee":null,"assignees":[],"requested_reviewers":[],"requested_teams":[],"labels":[],"milestone":null,"commits_url":"https://api.github.com/repos/opentracing/opentracing.io/pulls/316/commits","review_comments_url":"https://api.github.com/repos/opentracing/opentracing.io/pulls/316/comments","review_comment_url":"https://api.github.com/repos/opentracing/opentracing.io/pulls/comments{/number}","comments_url":"https://api.github.com/repos/opentracing/opentracing.io/issues/316/comments","statuses_url":"https://api.github.com/repos/opentracing/opentracing.io/statuses/9848c9f3f6aea2e3f8fe8a5b43fe728c372fc6a1","head":{"label":"PikBot:java_inject","ref":"java_inject","sha":"9848c9f3f6aea2e3f8fe8a5b43fe728c372fc6a1","user":{"login":"PikBot","id":35295607,"node_id":"MDQ6VXNlcjM1Mjk1NjA3","avatar_url":"https://avatars2.githubusercontent.com/u/35295607?v=4","gravatar_id":"","url":"https://api.github.com/users/PikBot","html_url":"https://github.com/PikBot","followers_url":"https://api.github.com/users/PikBot/followers","following_url":"https://api.github.com/users/PikBot/following{/other_user}","gists_url":"https://api.github.com/users/PikBot/gists{/gist_id}","starred_url":"https://api.github.com/users/PikBot/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/PikBot/subscriptions","organizations_url":"https://api.github.com/users/PikBot/orgs","repos_url":"https://api.github.com/users/PikBot/repos","events_url":"https://api.github.com/users/PikBot/events{/privacy}","received_events_url":"https://api.github.com/users/PikBot/received_events","type":"User","site_admin":false},"repo":{"id":136783784,"node_id":"MDEwOlJlcG9zaXRvcnkxMzY3ODM3ODQ=","name":"opentracing.io","full_name":"PikBot/opentracing.io","owner":{"login":"PikBot","id":35295607,"node_id":"MDQ6VXNlcjM1Mjk1NjA3","avatar_url":"https://avatars2.githubusercontent.com/u/35295607?v=4","gravatar_id":"","url":"https://api.github.com/users/PikBot","html_url":"https://github.com/PikBot","followers_url":"https://api.github.com/users/PikBot/followers","following_url":"https://api.github.com/users/PikBot/following{/other_user}","gists_url":"https://api.github.com/users/PikBot/gists{/gist_id}","starred_url":"https://api.github.com/users/PikBot/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/PikBot/subscriptions","organizations_url":"https://api.github.com/users/PikBot/orgs","repos_url":"https://api.github.com/users/PikBot/repos","events_url":"https://api.github.com/users/PikBot/events{/privacy}","received_events_url":"https://api.github.com/users/PikBot/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/PikBot/opentracing.io","description":"OpenTracing website","fork":true,"url":"https://api.github.com/repos/PikBot/opentracing.io","forks_url":"https://api.github.com/repos/PikBot/opentracing.io/forks","keys_url":"https://api.github.com/repos/PikBot/opentracing.io/keys{/key_id}","collaborators_url":"https://api.github.com/repos/PikBot/opentracing.io/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/PikBot/opentracing.io/teams","hooks_url":"https://api.github.com/repos/PikBot/opentracing.io/hooks","issue_events_url":"https://api.github.com/repos/PikBot/opentracing.io/issues/events{/number}","events_url":"https://api.github.com/repos/PikBot/opentracing.io/events","assignees_url":"https://api.github.com/repos/PikBot/opentracing.io/assignees{/user}","branches_url":"https://api.github.com/repos/PikBot/opentracing.io/branches{/branch}","tags_url":"https://api.github.com/repos/PikBot/opentracing.io/tags","blobs_url":"https://api.github.com/repos/PikBot/opentracing.io/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/PikBot/opentracing.io/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/PikBot/opentracing.io/git/refs{/sha}","trees_url":"https://api.github.com/repos/PikBot/opentracing.io/git/trees{/sha}","statuses_url":"https://api.github.com/repos/PikBot/opentracing.io/statuses/{sha}","languages_url":"https://api.github.com/repos/PikBot/opentracing.io/languages","stargazers_url":"https://api.github.com/repos/PikBot/opentracing.io/stargazers","contributors_url":"https://api.github.com/repos/PikBot/opentracing.io/contributors","subscribers_url":"https://api.github.com/repos/PikBot/opentracing.io/subscribers","subscription_url":"https://api.github.com/repos/PikBot/opentracing.io/subscription","commits_url":"https://api.github.com/repos/PikBot/opentracing.io/commits{/sha}","git_commits_url":"https://api.github.com/repos/PikBot/opentracing.io/git/commits{/sha}","comments_url":"https://api.github.com/repos/PikBot/opentracing.io/comments{/number}","issue_comment_url":"https://api.github.com/repos/PikBot/opentracing.io/issues/comments{/number}","contents_url":"https://api.github.com/repos/PikBot/opentracing.io/contents/{+path}","compare_url":"https://api.github.com/repos/PikBot/opentracing.io/compare/{base}...{head}","merges_url":"https://api.github.com/repos/PikBot/opentracing.io/merges","archive_url":"https://api.github.com/repos/PikBot/opentracing.io/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/PikBot/opentracing.io/downloads","issues_url":"https://api.github.com/repos/PikBot/opentracing.io/issues{/number}","pulls_url":"https://api.github.com/repos/PikBot/opentracing.io/pulls{/number}","milestones_url":"https://api.github.com/repos/PikBot/opentracing.io/milestones{/number}","notifications_url":"https://api.github.com/repos/PikBot/opentracing.io/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/PikBot/opentracing.io/labels{/name}","releases_url":"https://api.github.com/repos/PikBot/opentracing.io/releases{/id}","deployments_url":"https://api.github.com/repos/PikBot/opentracing.io/deployments","created_at":"2018-06-10T06:05:40Z","updated_at":"2018-06-10T06:05:42Z","pushed_at":"2018-06-25T03:53:51Z","git_url":"git://github.com/PikBot/opentracing.io.git","ssh_url":"git@github.com:PikBot/opentracing.io.git","clone_url":"https://github.com/PikBot/opentracing.io.git","svn_url":"https://github.com/PikBot/opentracing.io","homepage":"http://opentracing.io","size":7322,"stargazers_count":0,"watchers_count":0,"language":"CSS","has_issues":false,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"archived":false,"open_issues_count":0,"license":{"key":"apache-2.0","name":"Apache License 2.0","spdx_id":"Apache-2.0","url":"https://api.github.com/licenses/apache-2.0","node_id":"MDc6TGljZW5zZTI="},"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"opentracing:v2.0","ref":"v2.0","sha":"6517850aa8448c7dfd0fda7a09e7a5c0610b41c9","user":{"login":"opentracing","id":15482765,"node_id":"MDEyOk9yZ2FuaXphdGlvbjE1NDgyNzY1","avatar_url":"https://avatars1.githubusercontent.com/u/15482765?v=4","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":48717396,"node_id":"MDEwOlJlcG9zaXRvcnk0ODcxNzM5Ng==","name":"opentracing.io","full_name":"opentracing/opentracing.io","owner":{"login":"opentracing","id":15482765,"node_id":"MDEyOk9yZ2FuaXphdGlvbjE1NDgyNzY1","avatar_url":"https://avatars1.githubusercontent.com/u/15482765?v=4","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.io","description":"OpenTracing website","fork":false,"url":"https://api.github.com/repos/opentracing/opentracing.io","forks_url":"https://api.github.com/repos/opentracing/opentracing.io/forks","keys_url":"https://api.github.com/repos/opentracing/opentracing.io/keys{/key_id}","collaborators_url":"https://api.github.com/repos/opentracing/opentracing.io/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/opentracing/opentracing.io/teams","hooks_url":"https://api.github.com/repos/opentracing/opentracing.io/hooks","issue_events_url":"https://api.github.com/repos/opentracing/opentracing.io/issues/events{/number}","events_url":"https://api.github.com/repos/opentracing/opentracing.io/events","assignees_url":"https://api.github.com/repos/opentracing/opentracing.io/assignees{/user}","branches_url":"https://api.github.com/repos/opentracing/opentracing.io/branches{/branch}","tags_url":"https://api.github.com/repos/opentracing/opentracing.io/tags","blobs_url":"https://api.github.com/repos/opentracing/opentracing.io/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/opentracing/opentracing.io/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/opentracing/opentracing.io/git/refs{/sha}","trees_url":"https://api.github.com/repos/opentracing/opentracing.io/git/trees{/sha}","statuses_url":"https://api.github.com/repos/opentracing/opentracing.io/statuses/{sha}","languages_url":"https://api.github.com/repos/opentracing/opentracing.io/languages","stargazers_url":"https://api.github.com/repos/opentracing/opentracing.io/stargazers","contributors_url":"https://api.github.com/repos/opentracing/opentracing.io/contributors","subscribers_url":"https://api.github.com/repos/opentracing/opentracing.io/subscribers","subscription_url":"https://api.github.com/repos/opentracing/opentracing.io/subscription","commits_url":"https://api.github.com/repos/opentracing/opentracing.io/commits{/sha}","git_commits_url":"https://api.github.com/repos/opentracing/opentracing.io/git/commits{/sha}","comments_url":"https://api.github.com/repos/opentracing/opentracing.io/comments{/number}","issue_comment_url":"https://api.github.com/repos/opentracing/opentracing.io/issues/comments{/number}","contents_url":"https://api.github.com/repos/opentracing/opentracing.io/contents/{+path}","compare_url":"https://api.github.com/repos/opentracing/opentracing.io/compare/{base}...{head}","merges_url":"https://api.github.com/repos/opentracing/opentracing.io/merges","archive_url":"https://api.github.com/repos/opentracing/opentracing.io/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/opentracing/opentracing.io/downloads","issues_url":"https://api.github.com/repos/opentracing/opentracing.io/issues{/number}","pulls_url":"https://api.github.com/repos/opentracing/opentracing.io/pulls{/number}","milestones_url":"https://api.github.com/repos/opentracing/opentracing.io/milestones{/number}","notifications_url":"https://api.github.com/repos/opentracing/opentracing.io/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/opentracing/opentracing.io/labels{/name}","releases_url":"https://api.github.com/repos/opentracing/opentracing.io/releases{/id}","deployments_url":"https://api.github.com/repos/opentracing/opentracing.io/deployments","created_at":"2015-12-28T23:37:19Z","updated_at":"2018-06-06T03:33:00Z","pushed_at":"2018-06-26T11:32:31Z","git_url":"git://github.com/opentracing/opentracing.io.git","ssh_url":"git@github.com:opentracing/opentracing.io.git","clone_url":"https://github.com/opentracing/opentracing.io.git","svn_url":"https://github.com/opentracing/opentracing.io","homepage":"http://opentracing.io","size":7313,"stargazers_count":59,"watchers_count":59,"language":"CSS","has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":78,"mirror_url":null,"archived":false,"open_issues_count":42,"license":{"key":"apache-2.0","name":"Apache License 2.0","spdx_id":"Apache-2.0","url":"https://api.github.com/licenses/apache-2.0","node_id":"MDc6TGljZW5zZTI="},"forks":78,"open_issues":42,"watchers":59,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/opentracing/opentracing.io/pulls/316"},"html":{"href":"https://github.com/opentracing/opentracing.io/pull/316"},"issue":{"href":"https://api.github.com/repos/opentracing/opentracing.io/issues/316"},"comments":{"href":"https://api.github.com/repos/opentracing/opentracing.io/issues/316/comments"},"review_comments":{"href":"https://api.github.com/repos/opentracing/opentracing.io/pulls/316/comments"},"review_comment":{"href":"https://api.github.com/repos/opentracing/opentracing.io/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/opentracing/opentracing.io/pulls/316/commits"},"statuses":{"href":"https://api.github.com/repos/opentracing/opentracing.io/statuses/9848c9f3f6aea2e3f8fe8a5b43fe728c372fc6a1"}},"author_association":"CONTRIBUTOR"}}
{"actor":{"display_login":"jpkrohling"}}