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

Jump to bottom

GA splunk-otel-js-web #240

Open
26 of 27 tasks
t2t2 opened this issue Jun 13, 2023 · 7 comments
Open
26 of 27 tasks

GA splunk-otel-js-web #240

t2t2 opened this issue Jun 13, 2023 · 7 comments
Assignees
@t2t2 @pellared

Comments

@t2t2
Copy link

t2t2 commented Jun 13, 2023

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?

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 pellared self-assigned this Jun 29, 2023
@pellared
Copy link
Contributor

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
Copy link
Contributor

pellared commented Jul 17, 2023 •
edited
Loading

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.

✔️

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

✔️

@pellared
Copy link
Contributor

pellared commented Jul 17, 2023 •
edited
Loading

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.

❌

Possibly more:

@pellared pellared mentioned this issue Jul 17, 2023
Open
@pellared
Copy link
Contributor

pellared commented Jul 17, 2023 •
edited
Loading

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
Copy link
Contributor

pellared commented Jul 17, 2023 •
edited
Loading

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 ❌

✔️ (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

❌

GitHub Actions

✔️

GitHub Applications

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

✔️

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 ❌
  • 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 ❌
  • 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.

❌

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
Copy link
Contributor

pellared commented Jul 17, 2023 •
edited
Loading

Currently blocked by:

@pellared
Copy link
Contributor

pellared commented Jul 18, 2023 •
edited
Loading

@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.

@pellared pellared assigned t2t2 and pellared and unassigned pellared Jul 18, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@t2t2 t2t2

@pellared pellared

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@t2t2 @pellared