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.

Sign up for GitHub

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

docs: update docs before release #57

Merged
merged 3 commits into from
Jan 31, 2024
+48 −58
Merged

docs: update docs before release #57

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
047cc64
update docs before release
pkanal Jan 31, 2024
07c9b35
Mary's edits
pkanal Jan 31, 2024
cd1bd3b
more PR README feedback
pkanal Jan 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion OSSMETADATA
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
osslifecycle=active
osslifecycle=experimental
81 changes: 38 additions & 43 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@

Honeycomb wrapper for [OpenTelemetry](https://opentelemetry.io) in the browser.
<!-- TODO: happy badges of the OTel versions we are using -->
<!-- TODO: evergreen question of whether to use fields or attributes -->
**STATUS: this library is ALPHA.**

Latest release:
Expand All @@ -15,29 +16,33 @@ Latest release:

This package sets up OpenTelemetry for tracing, using our recommended practices, including:

* Useful fields about the browser situation
* Useful extra attributes, or fields, related to the browser
* Easy configuration to send to Honeycomb
* Basic sampler to control event volume
* Basic sampler to control event volume (coming soon)
* Multi span attributes (coming soon)
* Convenient packaging
* An informative debug mode, including links to traces in Honeycomb
* An informative debug mode
* Links to traces in Honeycomb (coming soon)

// TODO: ask Phillip whether we must call this a distro instead of a wrapper. It's a wrapper.
<!-- TODO: determine whether we must call this a distro instead of a wrapper. -->

<!-- Things to come: smoke tests in multiple browsers, smoke tests for popular frameworks, CDN distribution -->

## Why use this?

This wrapper is a little ahead of OpenTelemetry, so that you can get the recommended fields in before they're completely standardized.

This wrapper is at least as stable as OpenTelemetry, because it is backwards-compatible as we update it to the latest OpenTelemetry versions, semantic conventions, and recommended practices.

We test this library, with its combination of OpenTelemetry dependencies, so that you can be confident that upgrades will work. It is tested with the latest versions of Chrome, Firefox, and Safari.
We test this library, with its combination of OpenTelemetry dependencies, so that you can be confident that upgrades will work.

This project provides a convenient distribution of all the code required to get traces from the browser. No package manager is required. (note: maybe not in alpha)
This project provides a convenient distribution of all the code required to get traces from the browser.

## Getting started

Install this library:

`npm install @honeycombio/opentelemetry-web`
`npm install @honeycombio/opentelemetry-web @opentelemetry/auto-instrumentations-web`

[Get a Honeycomb API key](https://docs.honeycomb.io/quickstart/#create-a-honeycomb-account).

Expand All @@ -55,36 +60,38 @@ const sdk = new HoneycombWebSDK({
sdk.start();
```

Build and run your application, and then look for data in Honeycomb. On the Home screen, choose your application from the dropdown at the top. Find some traces there.
Build and run your application, and then look for data in Honeycomb. On the Home screen, choose your application by looking for the service name in the dropdown at the top. Find some traces there.
pkanal marked this conversation as resolved.
Show resolved Hide resolved

![Honeycomb screen, with "Home" circled on the left, and the dropdown circled at the top.](docs/honeycomb-home.png)

## Configuration
## SDK Configuration

Pass these options to the HoneycombWebSDK:

| name | required? | type | default value | description |
| --------------------- | ------------------------------------------------ | ------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *apiKey* | required[*](#send-to-an-opentelemetry-collector) | string | | [Honeycomb API Key](https://docs.honeycomb.io/working-with-your-data/settings/api-keys/) for sending traces directly to Honeycomb |
| *serviceName* | optional | string | unknown_service | The name of this browser application. Your telemetry will go to a Honeycomb dataset with this name. |
| *localVisualizations* | optional | boolean | false | For each trace created, print a link to the console so that you can find it in Honeycomb. Super useful in development! Do not use in production. |
| sampleRate | optional | number | 1 | If you want to send a random fraction of traces, then make this a whole number greater than 1. Only 1 in `sampleRate` traces will be sent, and the rest never be created. |
| apiKey | required[*](#send-to-an-opentelemetry-collector) | string | | [Honeycomb API Key](https://docs.honeycomb.io/working-with-your-data/settings/api-keys/) for sending traces directly to Honeycomb |
pkanal marked this conversation as resolved.
Show resolved Hide resolved
| serviceName | optional | string | unknown_service | The name of this browser application. Your telemetry will go to a Honeycomb dataset with this name. |
| localVisualizations** | optional | boolean | false | For each trace created, print a link to the console so that you can find it in Honeycomb. Super useful in development! Do not use in production. |
| sampleRate** | optional | number | 1 | If you want to send a random fraction of traces, then make this a whole number greater than 1. Only 1 in `sampleRate` traces will be sent, and the rest never be created. |
| tracesEndpoint | optional | string | `${endpoint}/v1/traces` | Populate this to send traces to a route other than /v1/traces |
pkanal marked this conversation as resolved.
Show resolved Hide resolved
| debug | optional | boolean | false | Enable additional logging |
pkanal marked this conversation as resolved.
Show resolved Hide resolved
| tracesApiKey | optional | string | | If traces should go to a different place than metrics(?), put the traces-only API key here. |
| dataset | optional | string | | Populate this only if your Honeycomb team is still [Classic](https://docs.honeycomb.io/honeycomb-classic/#am-i-using-honeycomb-classic) |
pkanal marked this conversation as resolved.
Show resolved Hide resolved
| skipOptionsValidation | optional | boolean | false | Do not require any fields.[*](#send-to-an-opentelemetry-collector) |

### Send to an OpenTelemetry Collector
| skipOptionsValidation** | optional | boolean | false | Do not require any fields.[*](#send-to-an-opentelemetry-collector) |
pkanal marked this conversation as resolved.
Show resolved Hide resolved

`*` Note: the `apiKey` field is required because this SDK really wants to help you send data directly to Honeycomb.

In production, we recommend running an OpenTelemetry Collector, so that your browser app can send traces to its origin.
`**` Note: these config options are planned but not implemented yet, they will be available as part of the beta release.

### Send to an OpenTelemetry Collector

In production, we recommend running an [OpenTelemetry Collector](https://docs.honeycomb.io/getting-data-in/otel-collector/#browser-telemetry), so that your browser app can send traces to it for you to have control over your Honeycomb API key as well any data transformation.
Your OpenTelemetry Collector can send the traces on to Honeycomb, and your API key will be in the Collector's configuration. Here is a configuration of the Honeycomb Web SDK that sends to your Collector:

```js
{
endpoint: "/",
endpoint: "http(s)://<your-collector-url>",
serviceName: "your-spiffy-browser-application",
skipOptionsValidation: true // because we are not including apiKey
}
Expand All @@ -102,23 +109,23 @@ The SDK adds these fields to all telemetry:

| name | status | static? | description | example |
|------|--------|---------|-------------|---------|
| user_agent.original | [stable](https://github.com/scheler/opentelemetry-specification/blob/browser-events/specification/resource/semantic_conventions/browser.md) | static | window.user_agent | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36` |
| browser.height | planned | per-span | [window.innerHeight](https://developer.mozilla.org/en-US/docs/Web/API/Window/innerHeight), the height of the layout viewport in pixels | 287 |
| browser.width | planned | per-span | [window.innerWidth](https://developer.mozilla.org/en-US/docs/Web/API/Window/innerWidth), the height of the layout viewport in pixels | 1720 |
| browser.brands | stable | static | [NavigatorUAData: brands](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorUAData/brands) | ["Not_A Brand 8", "Chromium 120", "Google Chrome 120"] |
| browser.platform | stable | static | [NavigatorUAData: platform](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorUAData/platform) | "Windows" |
| browser.mobile | stable | static | [NavigatorUAData: mobile](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorUAData/mobile) | true |
| browser.language | stable | static | [Navigator: language](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language) | "fr-FR" |
| browser.touch_screen_enabled | stable | static | [Navigator: maxTouchPoints](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/maxTouchPoints) | true |
| `user_agent.original` | [stable](https://github.com/scheler/opentelemetry-specification/blob/browser-events/specification/resource/semantic_conventions/browser.md) | static | window.user_agent | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36` |
| `browser.height` | planned | per-span | [window.innerHeight](https://developer.mozilla.org/en-US/docs/Web/API/Window/innerHeight), the height of the layout viewport in pixels | 287 |
| `browser.width` | planned | per-span | [window.innerWidth](https://developer.mozilla.org/en-US/docs/Web/API/Window/innerWidth), the height of the layout viewport in pixels | 1720 |
| `browser.brands` | stable | static | [NavigatorUAData: brands](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorUAData/brands) | ["Not_A Brand 8", "Chromium 120", "Google Chrome 120"] |
| `browser.platform` | stable | static | [NavigatorUAData: platform](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorUAData/platform) | "Windows" |
| `browser.mobile` | stable | static | [NavigatorUAData: mobile](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorUAData/mobile) | true |
| `browser.language` | stable | static | [Navigator: language](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language) | "fr-FR" |
| `browser.touch_screen_enabled` | stable | static | [Navigator: maxTouchPoints](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/maxTouchPoints) | true |
| `page.url` | custom | per-span | | `https://docs.honeycomb.io/getting-data-in/data-best-practices/#datasets-group-data-together?page=2` |
| `page.route` | custom | per-span | | `/getting-data-in/data-best-practices/` |
| `page.search` | custom | per-span | | `?page=2` |
| `page.hash` | custom | per-span | | `#datasets-group-data-together` |
| `page.hostname` | custom | per-span | | `docs.honeycomb.io` |
| `screen.width` | custom | static | Total available screen width in pixels. | `780` |
| `screen.height` | custom | static | Total available screen height in pixels | `1000` |
| honeycomb.distro.version | stable | static | package version | "1.2.3" |
| honeycomb.distro.runtime_version | stable | static | | "browser"
| `honeycomb.distro.version` | stable | static | package version | "1.2.3" |
| `honeycomb.distro.runtime_version` | stable | static | | "browser" |
| `entry_page.url` | custom | static | | `https://docs.honeycomb.io/getting-data-in/data-best-practices/#datasets-group-data-together?page=2` |
| `entry_page.path` | custom | static | | `/getting-data-in/data-best-practices/` |
| `entry_page.search` | custom | static | | `?page=2` |
Expand All @@ -128,19 +135,7 @@ The SDK adds these fields to all telemetry:

Static fields are added to the [Resource](https://opentelemetry.io/docs/concepts/resources/), so they are same for every span emitted for the loaded page.

Fields that can change during the lifetime of the page are instead added to each span in a SpanProcessor.

## When to stop using this

The parts of this wrapper are available separately.

You can copy the [initialization](the-relevant-code.js) of the SDK and customize it for yourself.

The UsefulBrowserFieldsSpanProcessor is available as a separate component. (or copy the code)

The sampler is available as a separate package. // link

The BaggageSpanProcessor is a separate package. // link
Fields that can change during the lifetime of the page are instead added to each span in a [SpanProcessor](https://opentelemetry.io/docs/specs/otel/trace/sdk/#span-processor).

## Migration Practices

Expand All @@ -162,7 +157,7 @@ When that code is in place upstream, we remove it here, and release a new versio

### Fields

This project adds fields to the outgoing spans. We follow semantic convention when it exists.
This project adds fields to the outgoing spans. We follow semantic convention when they exist.

For fields that aren't yet part of the semantic conventions, we give them a name. If those field names become stable with a different name, then:

Expand All @@ -176,7 +171,7 @@ For fields that aren't yet part of the semantic conventions, we give them a name

The configuration accepted by this wrapper is based on the options available in the OpenTelemetry libraries.

When an option is not available upstream, we give it a name. If that options becomes available upstream under a different name, we migrate to that.
When an option is not available upstream, we give it a name. If that option becomes available upstream under a different name, we migrate to that.

1. We add the new name, and accept both for 6 months.
1. We mark the old name as deprecated in this documentation, and issue a warning in debug mode.
Expand Down
6 changes: 4 additions & 2 deletions SUPPORT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# How to Get Help

// TODO: put more in here. We actually want to hear from people
This project uses GitHub issues to track bugs, feature requests, and questions about using the project.

This project uses GitHub issues to track bugs, feature requests, and questions about using the project. Please search for existing issues before filing a new one.
This distribution of OpenTelemetry aims to make using OpenTelemetry in the browser easier and more useful. If you have ideas for browser fields or other ways of making this easier to use, please open an issue!

Please search for existing issues before filing a new one.
2 changes: 1 addition & 1 deletion examples/hello-world-web/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ const main = () => {
const sdk = new HoneycombWebSDK({
// To send direct to Honeycomb, set API Key and comment out endpoint
// apiKey: 'api-key',
endpoint: 'http://localhost:4318/v1/traces', // send to local collector
endpoint: 'http://localhost:4318', // send to local collector
serviceName: 'web-distro',
debug: true,
instrumentations: [getWebAutoInstrumentations()], // add auto-instrumentation
Expand Down
Loading