Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add content for Java's Tracers. #311

Merged
merged 2 commits into from
Jul 5, 2018
Merged

Conversation

carlosalberto
Copy link

No description provided.

Copy link
Contributor

@jpkrohling jpkrohling left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a great start!



For example, initializing the **Tracer** implementation of `Jaeger` looks like this:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/looks like this/might look like this/

The "might" is because it could be also as simple as Configuration.fromEnv().getTracer()

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

might look like this

:) Makes sense, definitely.

```

One a **Tracer** instance is obtained, it can be used to manually create **Span**, or pass it to existing instrumentation for frameworks and libraries:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/One/Once/

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Damn, thanks, will fix ;)

// OpenTracing Redis client. It can be *any* OT-compatible tracer.
Tracer tracer = ...;
new TracingJedis(tracer);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice name, I had to double check this was the real name, not a typo :D

#### Global Tracer

In order to not force the user to keep around a **Tracer**, the **io.opentracing.util** artifact includes a helper **GlobalTracer** class implementing the **io.opentracing.Tracer**, which, as the name implies, acts as as a global instance that can be used from anywhere. It works by forwarding all operations to another underlying **Tracer**, that will get registered at some future point.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be better to state the actual artifact coordinates using the standard g:a[:v] notation: io.opentracing:opentracing-util, possibly with a link to the git repository?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I covered this in the Intro section. Think we should put them here as well?


```java
((CustomTracer)tracer).customFeature(100);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we should add a unwrap(Class<Tracer>) method to the interface, to avoid this cast here... Similar to what JPA has.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, yes, I wondered about the same. Sounds like we should open an Issue in the java repo to keep track of this potential improvement?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@@ -2,7 +2,67 @@
title: "Java: Tracers"
---

* Setting up your tracer
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about a small intro here? Something like:

A Tracer is the actual implementation that will record the spans and publish them somewhere. How your application handles the actual Tracer is up to you: either consume it directly throughout your application or store it in the GlobalTracer for easier usage with instrumented frameworks.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense, will add it.

// Get the actual OpenTracing-compatible Tracer.
Tracer tracer = config.getTracer();
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be worth mentioning the Tracer Resolver as well. Something like:

If your tracer supports it, the TracerResolver can also be used. With this approach, there's no tracer-specific initialization code in your application: Tracer tracer = TracerResolver.resolveTracer();

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, yes, had forgotten about it ;)

@@ -2,7 +2,67 @@
title: "Java: Tracers"
---

* Setting up your tracer
* Using the Global Tracer
* Accessing the Active Span
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess it's missing this item: "Accessing the Active Span"

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I covered that in the Scopes section (scopes.md, that is)

@carlosalberto
Copy link
Author

Updated ;)

@jpkrohling
Copy link
Contributor

Looks great! I'll let @tedsuo or another native speaker proofread/merge.

@jpkrohling jpkrohling mentioned this pull request Jun 27, 2018
@tedsuo
Copy link
Member

tedsuo commented Jul 5, 2018

Thanks!

@tedsuo tedsuo merged commit 9cdfd67 into opentracing:v2.0 Jul 5, 2018
yurishkuro pushed a commit that referenced this pull request Oct 5, 2018
* Hugo migration (#264)

* add theme scaffolding and basic hugo config

* add editorconfig file

* add baseline templating logic

* variablize theme in make commands

* add head partial

* add partial for javascript loading

* add basic templates for list and section pages

* add default taxonomy page

* add baseline archetype for docs

* add default taxonomy pages

* add 404 page

* interlink taxonomy pages

* add rudimentary navbar

* add more robust default single.html template

* add baseline SEO template

* add automatic robots.txt generation

* remove unnecessary env vars from make commands

* add assets pipeline

* finish CSS pipeline

* add theme to site config

* add firebase deployment support

* add firebase deployment option

* remove jekyll references from sass files

* finish migrating main page

* add iteration logic to navbar header

* add baseline docs template

* fix indentation discrepancy in bash window

* add favicon to metadata

* add docs-specific Sass assets

* add documentation.scss

* add missing links in navbar dropdown

* fix URLs for icons

* add proper list logic for navbar dropdown links

* remove /documentation links from navbar links

* ensure sticky footer using flexbox

* bring hero in line with current site

* fix variable error

* remove unnecessary data files

* add bootstrap import and fix footer

* move footer Sass into footer.scss

* minor padding adjustment for footer links

* fix navbar text color issue

* fix link color in hero

* fix color problem for community link in navbar

* basic CSS for docs template

* Add specification submodule

* add layouts for specification documents

* add API page templates

* remove unused Jekyll data assets

* add figures to main doc

* Add initial table styling

* Add opentracing-contrib/meta submodule

* remove specification file renaming logic

* add basic netlify config and build steps

* add netlify setup step to CI

* use more recent node version for netlify CI

* add netlify-setup command to netlify build commands

* add git submodule step to setup

* remove unnecessary assets

* add specification files to /content

* add missing specification files

* shorten spec titles

* fix issue with logo

* fix issue with home page header triangle

* add syntax CSS

* use DEPLOY_PRIME_URL for netlify preview builds

* fix template error

* Bugfix and document local setup procedure (#267)

* Ensure submodules are installed with --init

* Install theme dependencies on setup

* Add local dev instructions to README

* remove outdated contributing file

* update submodules to latest

* Simplify makefile (#292)

* Revert "Simplify makefile (#292)"

This reverts commit 5c9001a.

* Fix Makefile changes not to use nvm (#293)

* Adding pages to "404: Page not found" links (#294)

Signed-off-by: Prakriti <[email protected]>

- Fixes all broken links
- Adding new pages with some dummy content

* Copy/paste legacy content into v2.0 framework. (#295)

* first pass at rearanging the docs

* Adding sidebar nav for "Get Involved" (#296)

Signed-off-by: Prakriti <[email protected]>

- Fixes some broken links

* Add line about Hugo version number (#297)

* Temporary Hugo instructions

* fix for hugo v0.42

* java and go notes

* more guide notes

* Filling in "Get Involved" section of v2.0 (#299)

Signed-off-by: Prakriti <[email protected]>

* Docs navigation plus syntax highlighting (#298)

* Add docs nav and syntax highlighting

Signed-off-by: lucperkins <[email protected]>

* remove unused description

Signed-off-by: lucperkins <[email protected]>

* Bump Hugo version in Netlify config to 0.41

Signed-off-by: lucperkins <[email protected]>

* Updated OpenTracing overview topic.  Changed Overview to be first in the main menu. (#302)

* Write golang quick start documentation (#301)

Signed-off-by: Won Jun Jang <[email protected]>

* Adding Katacoda topic with links to courses. (#303)

* Adding links to tutorials. (#307)

* Add content for Java's Scopes. (#306)

* added spans and tags/logs/bags to overview (#308)

* Created a first draft of an FAQ. (#309)

* Adding documentation for Java:Spans (#312)

Signed-off-by: Prakriti <[email protected]>

* Add Content: Python Quickstart (#313)

* Adding the rough outline of the quickstart

* First stab at the quickstart

* Add a link to the opentracing tutorial, credit to Yuri

* Add Content: Python Quickstart (#314)

* Adding the rough outline of the quickstart

* First stab at the quickstart

* Add a link to the opentracing tutorial, credit to Yuri

* More cleanup, stub out full sections

* Add section for tracing HTTP requests with example

* Adding images for the quickstart in Python

* Just make sure we leave the WIP in a decent state

* Get rid of erroneous equals

* Add final bit about tagging and viewing

* Update image with misspelling

* Add content for Java's Intro. (#310)

* Add content for Java's Tracers. (#311)

* Add Java:Inject and Extract docs (#316)

* Add python inject-extract docs (#318)

* Add docs for tracers (#317)

* Hugo Sass pipeline (#326)

* Replace Gulp-based assets pipeline with native Hugo pipeline

Signed-off-by: lucperkins <[email protected]>

* Add vendored Bootstrap Sass assets

Signed-off-by: lucperkins <[email protected]>

* Add resources folder to Git

Signed-off-by: lucperkins <[email protected]>

* Add docs for Python:Spans (#323)

* Add intro to distributed tracing doc (#327)

Signed-off-by: Prakriti <[email protected]>

* Remove redundant tracing systems list (#328)

Signed-off-by: Prakriti <[email protected]>

* [WIP] General website fixes (#329)

* Fix header on guide TOC and remove unused files

Signed-off-by: lucperkins <[email protected]>

* Update Netlify version

Signed-off-by: lucperkins <[email protected]>

* Small CSS fixes

* Add TOC for docs

* Add model docs guides for Ruby & Go (#331)

Signed-off-by: Prakriti <[email protected]>

* Fix Makefile build commands

* Remove unnecessary .gitignore

* Remove unnecessary items from main .gitignore

* Remove node_modules directory and pare down resources directory

* Remove generated CSS file

* WIP: section-based nav for docs

* fixed nesting and linking; docs now have sane subsections

* update gitignore

* un-update gitignore

* update guides and docs sections to support new menu style + css/js for new menus

* fix menu js
fix link

* implement videos section

* add intro guide content and need help banner

* update description of LightStep on tracers page

* Readme and Makefile improvements

* `make` builds site by default
* Instructions for setting up locally have been updated

* fix guide list
drop down section header in menu on top level item selected
publish service mesh items

* migrate get-involved content to live in content dir
add outreachy 2019 page
remove unneded files

* big page structure cleanup
- moved intro pages to top level _indexes of each subsection
- added intro content from ot api language readmes where appropriate

* footer project section should auto-gen from content

* update footer font to bold

* clean up toc in spec/project pages

* adjust weights

* fix broken homepage links

* fixup broken links around site

* fix broken link

* fix broken links
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants