GA splunk-otel-js-web

[t2t2]

Which GDI repository do you wish to GA?

signalfx/splunk-otel-js-web

Does the repository follow the latest tagged minor release in GDI specification?

• Has an appropriate maintainers team.
  https://github.com/orgs/signalfx/teams/gdi-js-maintainers
• Permissions set correctly.
• Branch protection in place.
• Dependencies appropriately locked down.
  ** See note below
• GitHub Applications set up per spec.
• Follows the configuration requirements, if appropriate.
• Follows the semantic convention requirements, if appropriate.
• Required Files in place.
  • CHANGELOG.md
  • CODE_OF_CONDUCT.md
  • CONTRIBUTING.md
  • .github/CODEOWNERS
  • LICENSE
  • README.md
    • Build status badge
    • Getting started
    • Troubleshooting
    • Link to official Splunk docs
    • License information
  • SECURITY.md
• Releases done to spec.
• Type specific requirements (remove what doesn't apply)
  • Real User Monitoring Library
    • Documents all supported configuration parameters.
      https://docs.splunk.com/Observability/gdi/get-data-in/rum/browser/configure-rum-browser-instrumentation.html
    • Documents how to configure manual instrumentation.
      https://docs.splunk.com/Observability/gdi/get-data-in/rum/browser/migrate-manual-instrumentation.html
    • Documents supported instrumentation.
      https://docs.splunk.com/Observability/gdi/get-data-in/rum/browser/rum-browser-data-model.html
    • Documents supported platforms.
      https://docs.splunk.com/Observability/gdi/get-data-in/rum/browser/install-rum-browser.html

How long has the GDI repository been public?

2½+ years

Is the repository known to be used today?

Yes

Is there a date by which this approval is needed?**

No

Additional context

** - Dependencies in the published package aren't locked down due to open telemetry's micropackage architecture (yuck) and npm's module resolution (which allows installing a package multiple times to satisfy different version ranges) causing inflated bundle sizes when used as npm package (see doc linked in APMI-3362). For in-repository development, version locking is done via npm lockfile, these versions get used to generate bundles attached to releases and uploaded to CDN.

[pellared]

I plan to start reviewing it tomorrow. Feel free to sync with me if you have any questions beforehand or you have any suggestions or remarks.

[pellared]

https://github.com/signalfx/gdi-specification/blob/v1.5.0/specification/configuration.md

One or more configuration variables may be needed to properly configure GDI
repositories. Components that can be configured with environment variables MUST
support configuration of these variables using environment variables. Any
component that cannot be configured with environment variables MUST support
configuration of these variables using an alternate method. Any component MAY
support configuration of these variables by additional methods.

✖️ RUM is an exception

GDI repositories MUST adopt stable and SHOULD adopt experimental configuration
variables in the OpenTelemetry
Specification
before proposing variables to the GDI specification. If a new configuration
variable is needed by a GDI repository it MUST be brought to the GDI
specification as a GitHub issue. The GDI specification maintainers SHOULD
consider introducing needed configuration variables to the OpenTelemetry
repository before approving Splunk-specific configuration variables.

✖️ RUM is an exception

If a GDI repository requires an immediate configuration variable that is not
available in the OpenTelemetry specification and not available in the GDI
specification, the repository MAY introduce a repository-specific configuration
variable until the GDI specification maintainers make a decision. Any
repository-specific configuration variable defined SHOULD be prefixed with
SPLUNK_ and MUST NOT be marked as stable unless added to the GDI
specification. Upon resolution by the GDI specification, the GDI repository MUST
change the repository-specific configuration variable by the repository's next minor
release. This change MAY result in a breaking change so caution should be
exhibited when considering repository-specific configuration variables.

✔️

Splunk-specific configuration variables defined in the GDI specification MUST
be prefixed with SPLUNK_. Furthermore, configuration specific to Splunk
Observability Cloud MUST be prefixed with SPLUNK_OBSERVABILITY_ and to Splunk
Enterprise or Splunk Cloud MUST be prefixed with SPLUNK_PLATFORM_. If a
Splunk-specific configuration variable is declared as stable in the GDI
specification and later the OpenTelemetry specification declares a similar
variable as stable, the GDI specification MUST adopt the OpenTelemetry
configuration variable and SHOULD mark the GDI specification configuration
variable as deprecated by the next minor release. In addition to defining
Splunk-specification configuration variables, the GDI specification MAY require
specific OpenTelemetry configuration variables be supported. If it does, the
GDI specification MAY require certain values be supported including a specific
default value.

• Real User Monitoring configuration naming #246

✔️

Whenever a configuration variable changes its name, a stable GDI repository
(version >= 1.0) MUST support both old and new names until the next major
release is done. The old configuration variable MUST NOT be removed in a minor
release. GDI repositories that are not yet stable (version < 1.0) SHOULD follow
this rule, but they are not required to. When it is detected that a user uses
the old configuration variable a warning SHOULD be logged: the warning SHOULD
state that the old variable is deprecated, the new one should be used instead,
and that the old one will be removed in the next major release (not stable GDI
repositories MAY remove deprecated features in any future release).

✔️

Installation and configuration MUST optimize for customer experience and
time-to-value. Installation and configuration MAY provide a mechanism for
advanced or custom settings. As an example, the default installation for
instrumentation libraries should provide everything needed to configure W3C and
B3 as well as OTLP and Jaeger Thrift even though the default configuration is
set to W3C and OTLP. Installing all of these dependencies by default may result
in a large package, but makes it easy for users to switch settings via
configuration. An advanced installation process can be provided where the user
chooses what to install limiting the configuration options.

✔️

Real User Monitoring (RUM) instrumentation libraries cannot use environment
variables for configuration. Instead, they MUST expose a SplunkRum
object/class/namespace (depending on the language used) that allows setting the
properties listed below (in a language-specific way: Java may use builders,
Swift can use named parameters with default values, JavaScript can use objects,
etc.).

RUM instrumentation libraries MUST support the following configuration
properties:

Property (default value)	Description
realm ()	Splunk realm, e.g. us0, us1. If set, value of beaconEndpoint will be automatically computed based on this. [1] [2] [3]
beaconEndpoint ()	RUM beacon URL, e.g. https://rum-ingest.<realm>.signalfx.com/v1/rum. If both realm and beaconEndpoint are set, beaconEndpoint takes precedence. [1] [2] [3]
rumAccessToken ()	RUM authentication token. [1]
applicationName ()	Instrumented application name. [1]
globalAttributes ()	OpenTelemetry Attributes that will be added to every span produced by the RUM library.
deploymentEnvironment ()	Sets the environment (deployment.environment span attribute) for all spans.

• [1] Application name, authentication token and either realm or the beacon URL
  MUST be provided by the user. If any of these is missing, the RUM
  instrumentation library MUST fail to start.
• [2] Systems that allow implementations to enforce the beaconEndpoint value
  is https (i.e. not Android) MUST do so. These implementations need to
  reject/fail to start if this condition is not meet. Implementations MAY offer
  an unrecommended allowInsecureBeacon option (default false) that turns off
  the check.
• [3] If both realm and beaconEndpoint are set, a warning saying that
  realm will be ignored SHOULD be logged.

Other requirements:

• RUM library MUST use the Zipkin v2 JSON span exporter by default
• RUM library MUST limit the number of sent spans to 100 in a 30 second window
  per component attribute value

• Real User Monitoring configuration naming #246

✔️

[pellared]

https://github.com/signalfx/gdi-specification/blob/v1.5.0/specification/semantic_conventions.md

Runtime Environment Metrics

Status: Experimental

All Splunk distributions of OpenTelemetry
SHOULD collect
Runtime Environment Metrics
when metrics are enabled.

✖️ NOT REQUIRED and metrics are not supported

Real User Monitoring Spans and Attributes

Status: Experimental

Real User Monitoring (RUM) libraries MUST set the service.name resource
attribute to the value of the applicationName configuration property. This is
the only resource attribute that RUM libraries are supposed to set because it's
the only one the Zipkin exporter can understand.

The following attributes MUST be added to all spans produced by RUM libraries:

Name	Type	Description
app	string	The value of the applicationName property configured in SplunkRum; same as service.name resource attribute.
splunk.rumSessionId	string	The RUM session ID
splunk.rum.version	string	Version of the RUM library
component	string	Name of the instrumentation that produced this span

The following attributes MAY be added to all spans emitted by RUM libraries:

Name	Type	Description
deployment.environment	string	Value of the deploymentEnvironment property configured in SplunkRum, if any

Mobile RUM libraries (iOS, Android) MUST add device and system information to
all spans:

Name	Type	Description
device.model.name	string	Name of the device
os.name	string	iOS or Android
os.version	string	Version of the OS

Web RUM library MUST add the following attributes to all spans:

Name	Type	Description
location.href	string	Value of location.href at the moment of creating the span.
splunk.script_instance	string	A 64bit identifier, unique to every instance of the SplunkRum library.

• Stabilize Real User Monitoring Spans and Attributes #242

❌

Possibly more:

• Update semantic conventions for RUM #245

[pellared]

https://github.com/signalfx/gdi-specification/blob/v1.5.0/specification/versioning.md

All GDI repositories MUST be versioned according to Semantic Versioning
2.0. GDI repositories are versioned
separately from OpenTelemetry repositories as Splunk-specific breaking changes
MAY be introduced. GDI repositories MUST indicate what version of OpenTelemetry
repositories they are based on through release notes and SHOULD indicate through
logging. Additional version number constraints can be found in the sections
below.

❌ GDI repositories MUST indicate what version of OpenTelemetry repositories they are based on through release notes

TODO

Experimental

Everything in the specification starts as experimental, which covers alpha,
beta, and release candidate versions. Version numbers for releases MUST be less
than 1.0.0 while experimental. The minor version number SHOULD be increased
when significant or breaking changes are introduced.

While any section in the specification is experimental, breaking changes and
performance issues MAY occur. Sections SHOULD NOT be expected to be
feature-complete. In some cases, the experiment MAY be discarded and removed
entirely. Long-term dependencies SHOULD NOT be taken against experimental
sections.

GDI repositories MAY consist of one or more components. GDI repositories MUST be
designed in a manner that allows experimental components to be created without
breaking the stability guarantees of existing components. GDI repositories MUST NOT
be designed in a manner that breaks existing users when a new component beyond
the repository's first component transitions from experimental to stable. This
would punish users of the release candidate component, and hinder adoption.

Terms which denote stability, such as experimental MUST NOT be used as part
of a directory or import name. Package version numbers MAY include a suffix,
such as -alpha, -beta, -rc, or -experimental, to differentiate stable
and experimental components.

GDI repository components SHOULD start as experimental. All non-OpenTelemetry
experimental components MUST be disabled by default, MUST require a
configuration variable to enable, and MUST clearly be marked as experimental.

✔️

Stable

The initial stable release version number for GDI repositories MUST be 1.0.0 and
follow Semantic Versioning 2.0 for all subsequent releases. Once an
experimental component has gone through rigorous beta testing, it MAY
transition to stable. Long-term dependencies MAY now be taken against this
component. When a new stable component is introduced to a GDI repository with an
existing stable release, the MINOR version number MUST be incremented and the
component MUST clearly be marked as stable.

All components within a GDI repository MAY become stable together, or MAY
transition to stability component-by-component.

Different packaging options may exist for GDI repositories. Packaging MAY have
its own GDI repository. For example, the Helm chart for the Data Collector
exists in its own repository. Packaging that exists in a dedicated GDI
repository MAY go stable even if components contained within the packaging
are not stable.

Once a component is marked as stable, the following rules MUST apply
until the end of that component’s existence:

• Configuration Stability: Backward-incompatible changes to configuration,
  which includes environment variables and system properties, MUST NOT be made
  unless the MAJOR version number is incremented. All existing configuration
  parameters MUST continue to function against all future MINOR versions of
  the same MAJOR version.
• Component Stability: Stable components MUST be deprecated for at least
  six months before being removed. Deprecated components MUST be removed as
  part of a MAJOR version number increase but MAY remain deprecated across
  multple MAJOR versions. Deprecated components MUST continue to function
  until removed.
• Support: A MAJOR versions MUST be supported for one year following a
  new MAJOR version release. Support MUST includes security and critical bug
  fixes and SHOULD NOT include new features or enhancements. Security fixes
  MUST be provided as the latest PATCH version for the latest MINOR version
  of the latest MAJOR and SHOULD NOT be provided for previous PATCH or
  MINOR releases.

✔️

[pellared]

https://github.com/signalfx/gdi-specification/blob/v1.5.0/specification/repository.md

Teams

• MUST have a maintainers team and teams MAY be shared between repositories ✔️
  • MUST have -maintainers suffix ✔️
  • MUST include at least two currently full-time Splunkers ✔️
  • MUST NOT include any non-full-time Splunkers ✔️
• SHOULD have an approvers team and teams MAY be shared between repositories ✔️
  • MUST have -approvers suffix ✔️

✔️

Permissions

• MUST grant Admin permission
  level
  to maintainers team ✔️
• MUST grant Write permission
  level
  to approvers team and the signalfx/docs,
  signalfx/gdi-specification-approvers
signalfx/gdi-specification-maintainers teams ✔️
• MUST NOT grant Write, Maintain, Admin permission
  level
  to any other user nor team ❌
• MUST NOT grant any permission (including Read) to any individual ❌

• Add rule for bot account #244

✔️ (ADDRESSED)

Branch protection

• MUST have a default branch named main ✔️
• MUST NOT allow anyone (including administrators) pushing directly to main ✔️
• MUST require status checks to pass before merge to main ✔️
• MUST require at least one CODEOWNER to approve a PR prior to merge ✔️
• MUST require signed commits on main ✔️
• MUST NOT allow merge commit (squash or rebase merging only) ✔️

✔️

Dependencies

• MUST lock the versions of all build dependencies (e.g. libraries, binaries,
  scripts, docker images) or vendor them; EXCEPTION: tools that are
  available out-of-the-box on the CI runner

• Pin GitHub Actions versions and configure dependabot splunk-otel-js-web#607

• MUST enable Dependabot alerts ❌
  • MUST grant access to alerts for the approvers and maintainers teams ✔️
  • MUST enable Dependabot security updates ✔️
• MUST configure Dependabot version updates ❌

• Pin GitHub Actions versions and configure dependabot splunk-otel-js-web#607

❌

GitHub Actions

• MUST use GitHub
  secrets to
  store sensitive data (auth tokens, passwords) and limit their usage to only
  required places ✔️
• MUST NOT use Personal Access
  Tokens ✔️
• MUST limit permissions of
  GITHUB_TOKEN
  when used ✔️
  • MUST set the repository's default permission
    to just read access for the contents scope. ✔️
  • MUST only set the absolutely required permissions (least privilege) ✔️
  • MUST set permissions for individual jobs ✔️

✔️

GitHub Applications

• SHOULD have Codecov GitHub App configured ✖️ (NOT REQUIRED)
• SHOULD have Lychee Link Checker GitHub Action configured ✖️ (NOT REQUIRED)

• Add Lychee Link Checker GitHub Action splunk-otel-js-web#608

✔️

Required Files

• MUST have a CHANGELOG.md updated for every release ✔️
  • The CHANGELOG.md is intended to be consumed by humans, and not machines. ✔️
  • The file SHOULD contain an Unreleased section at the top, which includes
    changes that have not yet been released. ✔️
  • The file MUST be in reverse chronological order, with the most recent
    releases at the top of the file, after the Unreleased section. ✔️
  • Each release SHOULD be separated by a line separator (---) from the other relases. ✖️ (NOT REQUIRED)
  • Each release SHOULD contain separate sections for each major functionality
    area (if applicable). ✖️ (NOT REQUIRED)
    The following sub-sections MAY be used, as appropriate or specified.
    • General - General comments about the release that users should know about.
    • Breaking Changes - Any changes that will break backward compatibility
      with previous versions. MUST list all breaking changes.
    • Bugfixes - Details of bugs that were fixed. SHOULD list all bug fixes.
    • Enhancements - New features that have been added to the repository. SHOULD
      list all new features.
  • The CHANGELOG.md SHOULD NOT list every PR, but only changes significant
    from an end-user point of view. Anyone who is interested in all the details
    of every change in the repository can use the git log for that. ✔️
• MUST add CODE_OF_CONDUCT.md ✔️
• MUST add CONTRIBUTING.md ❌

• Update CONTRIBUTING.md splunk-otel-js-web#609

• MUST have a .github/CODEOWNERS file with
  a maintainers team ✔️
• SHOULD have an approvers team in CODEOWNERS ✔️
• MUST add LICENSE ✔️
• SHOULD have a MIGRATING.md if applicable ✖️ (NOT APPLICABLE)
• MUST have a README.md ✔️
  • MUST have a badge on the README.md with build status ✔️
    • CI and PR builds and all tests/checks that are executed in them MUST be
      publicly accessible by anyone.
  • MUST have a badge on the README.md with GDI specification version supported ❌

This needs to be done at the end.

• SHOULD have a badge on the README.md with code coverage, if appropriate. ✖️ (NOT REQUIRED)
• SHOULD have badges on the README.md for other relevant things including artifacts ✔️
• MUST have getting started information in README.md ✔️
• MUST have troubleshooting information in README.md ❌

• Add troubleshooting docs and reference them in README.md splunk-otel-js-web#610

• MUST link to official Splunk docs in README.md ✔️
• MUST have license information in README.md ✔️
• MAY have a RELEASING.md file that documents the release process, but this
  file MUST NOT document private processes. For repositories that use private release
  jobs, the RELEASING.md file SHOULD be absent or, if included, just contain
  the following note: ✖️ (NOT REQUIRED)

  The release process involves signing built packages and binaries and thus
  must be kept private and not exposed publicly.

• MUST add the SECURITY.md ✔️
  • SHOULD add dependabot information to SECURITY.md if applicable ✖️ (NOT REQUIRED)

You can consider adding something like https://github.com/signalfx/splunk-otel-java/blob/main/SECURITY.md#dependencies

• SHOULD NOT contain comprehensive application examples. Application examples
  showing multi-system interactions or even cross-language use cases SHOULD be
  put in the Splunk OpenTelemetry example
  repository.
  Smaller, developer focused, examples MAY be included in the repository if it
  is customary to do so for the coding language used. ✖️ (NOT REQUIRED)

I feel like https://github.com/signalfx/splunk-otel-js-web/tree/main/examples/todolist should be moved to https://github.com/signalfx/tracing-examples/tree/main/opentelemetry-tracing

❌

GitHub Releases

• MUST have a signature or a checksum with signature for all release artifacts ✔️
  • SHOULD use Splunk signing key ✖️ (NOT APPLICABLE)
• MUST use signed tags ❌

None of the tag is signed.

• MUST have a tag protection rule
  for the release tags (e.g. v*) ✔️
• MUST state version of OpenTelemetry repository built against if applicable ❌

The latest releases does not tell it. This info should be added for each release.

• MUST update all examples in the Splunk OpenTelemetry example
  repository
  that depends on the repository to use the latest release. ✖️ (NOT APPLICABLE RIGHT NOW)

❌

Real User Monitoring Libraries

• MUST document all configuration parameters that are relevant
  to Splunk Observability Cloud ✔️
• MUST document all configuration parameters whose default or accepted values
  deviate from upstream ✔️
• MUST document how to configure manual instrumentation ✔️
• MUST document supported instrumentations ✔️
• MUST document supported platforms: browsers, OS versions, API requirements ✔️
• MAY host the documentation in the Observability Cloud documentation repository ✔️

✔️

[pellared]

Currently blocked by:

• Stabilize Real User Monitoring Spans and Attributes #242
• Pin GitHub Actions versions and configure dependabot splunk-otel-js-web#607
• Update CONTRIBUTING.md splunk-otel-js-web#609
• Add troubleshooting docs and reference them in README.md splunk-otel-js-web#610
• Add rule for bot account #244
• Update semantic conventions for RUM #245
• Real User Monitoring configuration naming #246

[pellared]

@t2t2 I did my best to review against GDI spec 1.5.0.

I created some issues, but some things are only noted as comments.