Added Plugin API docs #362

kjin · 2017-02-06T19:40:02Z

No description provided.

plugins.md

+example, to patch just `express` with a plugin named `TODO`:
+
+require('@google-cloud/trace-agent').start({
+  config: {


plugins.md

+The trace agent is driven by a set of plugins that describe how to patch a
+module to generate trace spans when that module is used. We provide plugins for
+some well-known modules such as express, mongodb, and http, and provide a plugin
+API for third-party developers to create their own.


plugins.md

+
+* `file`: The path to the file whose exports should be patched, relative to the
+  root of the module. You can specify an empty string, or omit this field
+  entirely, to specify the root itself.


plugins.md

+  entirely, to specify the root itself.
+* `versions`: A `semver` expression which will be used to control whether the
+  specified file will be patched based on the module version; the patch will
+  only be applied if the module version satisfies this expression. This might be


plugins.md

+Developers wishing to trace their applications may specify, in the
+[configuration][config-js] object passed to the trace agent, a `plugins` field
+with a key-value pair (module name, path to plugin). For
+example, to patch just `express` with a plugin named `TODO`:


plugins.md

+This function consults the trace agent's tracing policy to determine whether a
+trace span should actually be started or not. If the tracing policy prohibits
+a new span to be created under the current circumstances, this function will
+return `null` instead.


plugins.md

+Returns a Transaction object that corresponds to a root span started earlier
+in the same context, or `null` if one doesn't exist.
+
+#### `api.runInRootSpan(options, fn)`


plugins.md

+
+Gets the trace context serialized as a string.
+
+### Context Propagation


kjin · 2017-02-07T00:36:14Z

@GoogleCloudPlatform/node-team Mentioning well-known labels and constants here (forgot to do so in initial change): a40c762

plugins.md

+#### `transaction.endSpan() | childSpan.endSpan()`
+
+Ends the span associated with the calling object. This function should only be
+called once.


plugins.md

+`Transaction` and `ChildSpan`, respectively.
+
+#### `api.createTransaction(options)`
+* `options`: [`TraceOptions`](trace-span-options)


plugins.md

+  current application.
+- Parsing and serializing trace contexts for the sake of propagating them over
+  the network.
+- Binding callbacks and event emitters with a CLS namespace in order to


ofrobots · 2017-02-07T00:50:17Z

Would it be possible to generate these docs as a result of running jsdoc on the trace-plugin-api.js file. i.e. Can this doc be contained in comments in the source, or is there something intrinsic that requires this to be an externally maintained documentation?

plugins.md

+with a key-value pair (module name, path to plugin). For
+example, to patch just `express` with a plugin at `./plugins/plugin-express.js`:
+
+require('@google-cloud/trace-agent').start({


plugins.md

+
+### Cross-Service Trace Contexts
+
+The Trace Agent supports distributed tracing, so that in supported web


plugins.md

+  current application.
+- Parsing and serializing trace contexts for the sake of propagating them over
+  the network.
+- Binding callbacks and event emitters with a CLS namespace in order to


plugins.md

+
+Runs the given function in a child span corresponding to an incoming request.
+The provided function should accept a `ChildSpan` object, which represents a
+child span.


plugins.md

+  * A serialized trace context. If the module being traced is a web framework,
+    the plugin that patches this module should attempt to extract this from
+    an incoming request header and set this field. Omitting this field will
+    never cause an error, but may cause trace spans that correspond to a single


kjin · 2017-02-07T01:34:52Z

@ofrobots I did indeed find that I was copy-pasting a lot from the JSdocs. It's true that it would be a hassle to update both at once -- the merits I saw in a separate doc was that it could be organized differently (I'm grouping functions here by their purpose, while in the implementation they're grouped by prototype.). I think it's important to have a doc that developers can read from top-to-bottom (this file as it is might not satisfy this though.).

But since you mention it, I now think it would be best for me to remove the specifics of the functions from this doc (making sure that they're written in the JSDoc file), but I think the sections describing the plugin loader, config, and high-level overview of what the API does should stay, for the sake of having at least something centralized that can help plugin developers get started quickly.

plugins.md

+
+### Context Propagation
+
+#### `api.bind(fn)`


plugins.md

+
+Binds the given function to the current context.
+
+#### `api.bindEmitter(emitter)`


plugins.md

+* `file`: The path to the file whose exports should be patched, relative to the
+  root of the module. You can specify an empty string, or omit this field
+  entirely, to specify the export of the module itself.
+* `versions`: A `semver` expression which will be used to control whether the


plugins.md

+  might be useful if your plugin only works on some versions of a module, or if
+  you are patching internal mechanisms that are specific to a certain range of
+  versions.
+* `patch`: A function describing how the given file should be patched. It will


kjin · 2017-02-25T00:37:10Z

~~Updated: Newest changes @ 532e371~~

Updated: Everything has been put in README.md. Changes are best summarized in commits starting from 532e371. The changes to the text of plugins.md itself from 532e371 to 9b0c91a are minimal.

@GoogleCloudPlatform/node-team PTAL

README.md

@@ -137,82 +137,179 @@ The trace configuration additionally exposes the `samplingRate` option which set

 The custom tracing API can be used to add custom spans to trace. A *span* is a particular unit of work within a trace, such as an RPC request. Spans may be nested; the outermost span is called a *root span*, even if there are no nested child spans. Root spans typically correspond to incoming requests, while *child spans* typically correspond to outgoing requests, or other work that is triggered in response to incoming requests.

-For any of the web frameworks listed above (`express`, `hapi`, and `restify`), a root span is automatically started whenever an incoming request is received (in other words, all middleware already runs within a root span). If you wish to record a span outside of any of these frameworks, any traced code must run within a root span that you create yourself.
+For any of the web frameworks listed above (`express`, `hapi`, `koa` and `restify`), a root span is automatically started whenever an incoming request is received (in other words, all middleware already runs within a root span). If you wish to record a span outside of any of these frameworks, any traced code must run within a root span that you create yourself.


README.md

+
+### The `TraceApi` Object
+
+A `TraceApi` instance, in short, provides functions that facilitate the following:


README.md

+
+#### Trace Spans
+
+These functions provide the capability to create trace spans, add labels to them, and close them. `transaction` and `childSpan` are instances of `Transaction` and `ChildSpan`, respectively.


README.md

+  * Returns `any`
+  * Attempts to create a root span, run the given callback, and pass it a `Span` object if the root span was successfuly created. Otherwise, the given function is run with `null` as an argument. This may be for one of two reasons:
+    * The trace policy, as specified by the user-given configuration, disallows a root span from being created under the current circumstances.
+    * The trace agent is disabled, either because it wasn't started at all, started in disabled mode, or started in an environment where the GCP project ID could not be obtained.


README.md

+* `TraceApi#api.runInRootSpan(options, fn)`
+  * `options`: [`TraceOptions`](#trace-span-options)
+  * `fn`: `function(?Span): any`
+  * Returns `any`


README.md

+  * `options`: [`TraceOptions`](#trace-span-options)
+  * Returns `?Span`
+  * Attempts to create a child span, and returns a `Span` object if this is successful. Otherwise, it returns `null`. This may be for one of several reasons:
+    * A root span wasn't created beforehand because an earlier call to `runInRootSpan` didn't generate one.


README.md

+  * Optional for root spans, ignored for child spans
+  * The URL of the incoming request. This only applies if the module being
+    traced is a web framework. If given, a label will automatically be created
+    for the new span for the url (under the key `url`). This field will also be


README.md

+    for the new span for the url (under the key `url`). This field will also be
+    compared against the trace agent's URL filtering policy to check whether a
+    span should be created.
+  * Plugin developers should favor populating this field over using


README.md

+
+#### Trace Agent Configuration
+
+* `TraceApi#enhancedDatabaseReportingEnabled()`


README.md

+
+#### Cross-Service Trace Contexts
+
+The Trace Agent supports distributed tracing, so that in supported web frameworks, incoming requests that are known to come from other services that are also integrated with Stackdriver Trace (through the ['x-cloud-trace-context'][stackdriver-trace-faq] field in request headers) should build spans that are aware of the information serialized in this field, known as the trace context. (For more information, see the [Dapper][dapper-paper] paper describing the distributed tracing system.)


matthewloring · 2017-02-28T00:38:13Z

LGTM

changes to reflect the api's role in the agent just a few more things related to versioning reflect nullspan no longer being a thing

kjin requested review from ofrobots, matthewloring, cristiancavalli and DominicKramer February 6, 2017 19:40

googlebot added the cla: yes This human has signed the Contributor License Agreement. label Feb 6, 2017

DominicKramer reviewed Feb 6, 2017

View reviewed changes

plugins.md Outdated

example, to patch just `express` with a plugin named `TODO`:

require('@google-cloud/trace-agent').start({

config: {

This comment was marked as spam.

Sign in to view

This comment was marked as spam.

Sign in to view

matthewloring reviewed Feb 6, 2017

View reviewed changes

DominicKramer reviewed Feb 7, 2017

View reviewed changes

plugins.md Outdated

#### `transaction.endSpan() | childSpan.endSpan()`

Ends the span associated with the calling object. This function should only be

called once.

This comment was marked as spam.

Sign in to view

This comment was marked as spam.

Sign in to view

DominicKramer reviewed Feb 7, 2017

View reviewed changes

plugins.md Outdated

`Transaction` and `ChildSpan`, respectively.

#### `api.createTransaction(options)`

* `options`: [`TraceOptions`](trace-span-options)

This comment was marked as spam.

Sign in to view

This comment was marked as spam.

Sign in to view

DominicKramer reviewed Feb 7, 2017

View reviewed changes

ofrobots reviewed Feb 7, 2017

View reviewed changes

kjin force-pushed the plugin-docs branch from 0b19b1b to cf0fe8f Compare February 7, 2017 02:24

DominicKramer reviewed Feb 10, 2017

View reviewed changes

plugins.md Outdated

### Context Propagation

#### `api.bind(fn)`

This comment was marked as spam.

Sign in to view

DominicKramer reviewed Feb 10, 2017

View reviewed changes

plugins.md Outdated

Binds the given function to the current context.

#### `api.bindEmitter(emitter)`

This comment was marked as spam.

Sign in to view

This comment was marked as spam.

Sign in to view

DominicKramer reviewed Feb 10, 2017

View reviewed changes

matthewloring added this to the Beta milestone Feb 20, 2017

kjin force-pushed the plugin-docs branch from cb6f3b3 to 532e371 Compare February 25, 2017 00:36

kjin force-pushed the plugin-docs branch from 79d52b4 to 9b0c91a Compare February 25, 2017 02:06

matthewloring suggested changes Feb 25, 2017

View reviewed changes

kjin force-pushed the plugin-docs branch from 4c59a3c to d44b93c Compare February 28, 2017 00:32

matthewloring approved these changes Feb 28, 2017

View reviewed changes

kjin added 3 commits February 27, 2017 16:41

Added Plugin API docs

d66a912

Addressed low-hanging fruit

40e7af8

Added notes on well-known labels and constants

b006335

kjin added 9 commits February 27, 2017 16:41

Addressed some comments

b923be3

Added link to Dapper

c5d2a47

Update to reflect recent changes and also some notes on c. propagation

1b73ff8

updated docs to reflect recent changes

4f2297c

changes to reflect the api's role in the agent just a few more things related to versioning reflect nullspan no longer being a thing

Moved everything to README.md

31c9891

Change child span docs somewhat

590c882

updated list of built-in plugins

986e6dd

New changes

e56bc01

straight up cut-paste of trace api docs to new file

0b2e66c

kjin force-pushed the plugin-docs branch from d44b93c to 0b2e66c Compare February 28, 2017 00:49

kjin merged commit 2a374fd into googleapis:master Feb 28, 2017

kjin mentioned this pull request Feb 28, 2017

Trace API and Plugin Developer Docs #427

Merged


		Gets the trace context serialized as a string.

		### Context Propagation


		### Cross-Service Trace Contexts

		The Trace Agent supports distributed tracing, so that in supported web


		Binds the given function to the current context.

		#### `api.bindEmitter(emitter)`


		### The `TraceApi` Object

		A `TraceApi` instance, in short, provides functions that facilitate the following:


		#### Trace Spans

		These functions provide the capability to create trace spans, add labels to them, and close them. `transaction` and `childSpan` are instances of `Transaction` and `ChildSpan`, respectively.


		#### Trace Agent Configuration

		* `TraceApi#enhancedDatabaseReportingEnabled()`


		#### Cross-Service Trace Contexts

		The Trace Agent supports distributed tracing, so that in supported web frameworks, incoming requests that are known to come from other services that are also integrated with Stackdriver Trace (through the ['x-cloud-trace-context'][stackdriver-trace-faq] field in request headers) should build spans that are aware of the information serialized in this field, known as the trace context. (For more information, see the [Dapper][dapper-paper] paper describing the distributed tracing system.)

Added Plugin API docs #362

Added Plugin API docs #362

Conversation

kjin commented Feb 6, 2017

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

kjin commented Feb 7, 2017

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

ofrobots commented Feb 7, 2017

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

kjin commented Feb 7, 2017

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

kjin commented Feb 25, 2017 • edited Loading

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

matthewloring commented Feb 28, 2017

kjin commented Feb 25, 2017 •

edited

Loading