-
Notifications
You must be signed in to change notification settings - Fork 98
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
Added Plugin API docs #362
Conversation
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.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
plugins.md
Outdated
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. |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
plugins.md
Outdated
|
||
* `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. |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
plugins.md
Outdated
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 |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
plugins.md
Outdated
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`: |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
plugins.md
Outdated
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. |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
plugins.md
Outdated
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)` |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
plugins.md
Outdated
|
||
Gets the trace context serialized as a string. | ||
|
||
### Context Propagation |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
@GoogleCloudPlatform/node-team Mentioning well-known labels and constants here (forgot to do so in initial change): a40c762 |
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.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
plugins.md
Outdated
`Transaction` and `ChildSpan`, respectively. | ||
|
||
#### `api.createTransaction(options)` | ||
* `options`: [`TraceOptions`](trace-span-options) |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
plugins.md
Outdated
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 |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
Would it be possible to generate these docs as a result of running jsdoc on the |
plugins.md
Outdated
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({ |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
plugins.md
Outdated
|
||
### Cross-Service Trace Contexts | ||
|
||
The Trace Agent supports distributed tracing, so that in supported web |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
plugins.md
Outdated
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 |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
plugins.md
Outdated
|
||
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. |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
plugins.md
Outdated
* 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 |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
@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
Outdated
|
||
### Context Propagation | ||
|
||
#### `api.bind(fn)` |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
plugins.md
Outdated
|
||
Binds the given function to the current context. | ||
|
||
#### `api.bindEmitter(emitter)` |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
plugins.md
Outdated
* `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 |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
plugins.md
Outdated
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 |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
README.md
Outdated
@@ -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. |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
README.md
Outdated
|
||
### The `TraceApi` Object | ||
|
||
A `TraceApi` instance, in short, provides functions that facilitate the following: |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
README.md
Outdated
|
||
#### 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. |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
README.md
Outdated
* 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. |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
README.md
Outdated
* `TraceApi#api.runInRootSpan(options, fn)` | ||
* `options`: [`TraceOptions`](#trace-span-options) | ||
* `fn`: `function(?Span): any` | ||
* Returns `any` |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
README.md
Outdated
* `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. |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
README.md
Outdated
* 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 |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
README.md
Outdated
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 |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
README.md
Outdated
|
||
#### Trace Agent Configuration | ||
|
||
* `TraceApi#enhancedDatabaseReportingEnabled()` |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
README.md
Outdated
|
||
#### 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.) |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
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
No description provided.