docs: update docs before release (#57)

## Which problem is this PR solving? - Closes #40 ## Short description of the changes - Updated the README to reflect current state of the SDK - Updates to SUPPORT.md - Mark this project as experimental - Update example endpoint, removed `/v1/traces` path ## How to verify that this has the expected result - Smoke tests should still pass - Mary's review of the README. --------- Co-authored-by: Mary J. <[email protected]>
honeycombio · Jan 31, 2024 · e314015 · e314015
1 parent 920d29b
commit e314015
Show file tree

Hide file tree

Showing 4 changed files with 48 additions and 58 deletions.
diff --git a/OSSMETADATA b/OSSMETADATA
@@ -1 +1 @@
-osslifecycle=active
+osslifecycle=experimental
diff --git a/README.md b/README.md
@@ -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:
@@ -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).
 
@@ -55,70 +60,65 @@ 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 Dataset dropdown at the top. Data should populate.
 
 ![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. |
-| tracesEndpoint        | optional                                         | string  | `${endpoint}/v1/traces` | Populate this to send traces to a route other than /v1/traces                                                                                                             |
-| debug                 | optional                                         | boolean | false                   | Enable additional logging                                                                                                                                                 |
-| 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)                                   |
-| skipOptionsValidation | optional                                         | boolean | false                   | Do not require any fields.[*](#send-to-an-opentelemetry-collector)                                                                                                        |
-
-### Send to an OpenTelemetry Collector
+| 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. |
+| tracesEndpoint        | optional                                         | string  | `${endpoint}/v1/traces` | Populate this to send traces to a route other than /v1/traces.                                                                                                             |
+| debug                 | optional                                         | boolean | false                   | Enable additional logging.                                                                                                                                                 |
+| dataset               | optional                                         | string  |                         | Populate this only if your Honeycomb environment is still [Classic](https://docs.honeycomb.io/honeycomb-classic/#am-i-using-honeycomb-classic).                                   |
+| skipOptionsValidation** | optional                                         | boolean | false                   | Do not require any fields.[*](#send-to-an-opentelemetry-collector) Use with OpenTelemetry Collector.                                                                                                       |
 
 `*` 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
 }
 ```
 
 ## Fields emitted
 
-What do you get from this SDK?
-
-By default, no instrumentation is added.
-You can configure [automatic instrumentation](https://docs.honeycomb.io/getting-data-in/opentelemetry/browser-js/#automatic-instrumentation).
-You can also [add your own instrumentation](https://docs.honeycomb.io/getting-data-in/opentelemetry/browser-js/#adding-manual-instrumentation).
-
 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`                                                                                            |
@@ -128,19 +128,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
 
@@ -152,7 +140,7 @@ Our version numbers are independent of the OpenTelemetry version numbers. Check
 
 When OpenTelemetry releases a new version of the packages this project depends on, we update this project to use them within a week, unless our tests indicate a problem.
 
-When the OpenTelemetry API or SDK has a major version bump, this package will too. We also have major version bumps of our own.
+When the OpenTelemetry API or SDK has a major version bump, this package will, too. We also have major version bumps of our own.
 
 ### Code
 
@@ -162,7 +150,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:
 
@@ -176,7 +164,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.

diff --git a/SUPPORT.md b/SUPPORT.md
@@ -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.
diff --git a/examples/hello-world-web/index.js b/examples/hello-world-web/index.js
@@ -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