release @elastic/[email protected] (#356)

This also adds the workflow and script/doc updates to publish
mockotlpserver to npm and GitHub releases.

.github/workflows/release-mockotlpserver.yml

@@ -0,0 +1,52 @@
+# Release a tagged version of the '@elastic/mockotlpserver' package.
+name: release-mockotlpserver
+
+on:
+  push:
+    tags:
+      - mockotlpserver-v*.*.*
+
+# 'id-token' perm needed for npm publishing with provenance (see
+# https://docs.npmjs.com/generating-provenance-statements#example-github-actions-workflow)
+permissions:
+  contents: write
+  pull-requests: read
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 'v18.20.4'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm run ci-all
+
+      - name: npm publish
+        working-directory: ./packages/mockotlpserver
+        run: npm publish
+        env:
+          # https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages#publishing-packages-to-the-npm-registry
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: GitHub release
+        run: ./scripts/github-release.sh "packages/mockotlpserver" "${{ github.ref_name }}"
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+      - name: Notify in Slack
+        # Only notify on failure, because on success the published GitHub
+        # Release will result in a notification from the GitHub Slack app
+        # (assuming '/github subscribe elastic/elastic-otel-node').
+        if: ${{ failure() }}
+        uses: elastic/oblt-actions/slack/[email protected]
+        with:
+          bot-token: ${{ secrets.SLACK_BOT_TOKEN }}
+          channel-id: "#apm-agent-node"
+          message: '[${{ github.repository }}] Release `@elastic/mockotlpserver` *${{ github.ref_name }}*'

RELEASING.md

@@ -40,7 +40,26 @@ Assuming "x.y.z" is the release verison:
     https://github.com/elastic/elastic-otel-node/actions/workflows/release.yml
 
 
-## How to release other packages
+## How to release `@elastic/mockotlpserver`
 
-(No other packages in this repo are currently being published/released.)
+Assuming "x.y.z" is the release verison:
+
+1. Choose the appropriate version number according to semver.
+
+2. Create a PR with these changes:
+    - Bump the "version" in "packages/mockotlpserver/package.json".
+    - Run `npm install` in "packages/mockotlpserver/" to update "packages/mockotlpserver/package-lock.json".
+    - Update "packages/mockotlpserver/CHANGELOG.md" as necessary.
+    - Name the PR something like "release @elastic/[email protected]".
+
+3. Get the PR approved and merged.
+
+4. Working on the elastic repo (not a fork), tag the commit as follows:
+    ```
+    git tag mockotlpserver-vx.y.z
+    git push origin mockotlpserver-vx.y.z
+    ```
+    The GitHub Actions "release-mockotlpserver" workflow will handle the release
+    steps -- including the `npm publish`. See the appropriate run at:
+    https://github.com/elastic/elastic-otel-node/actions/workflows/release-mockotlpserver.yml
 

packages/mockotlpserver/CHANGELOG.md

@@ -1,7 +1,8 @@
 # @elastic/mockotlpserver Changelog
 
-## untagged
+## v0.4.0
 
+- First version being published to npm.
 - Fix normalization of *empty* `kvlistValue` attributes.
 - Improve "logs-summary" rendering of "Events" (log records with a `event.name`
   attribute) and log record `Body` fields that are multi-line strings or

packages/mockotlpserver/README.md

@@ -4,33 +4,54 @@ A mock OTLP server/receiver for development.
 receiving OTLP requests. The data in those requests are printed to the
 console. Various output formats are supported.
 
-# Install
+It also supports being run from Node.js code. This is used in the
+"../opentelemetry-node" package to assist with testing. A test is of the form:
+
+1. start the mockotlpserver
+2. run an instrumented script
+3. get the received OTLP data from the mock server and make assertions on that data.
 
-(This package is not yet published to npm, so you'll need a clone of
-this repo.)
 
-    git clone [email protected]:elastic/elastic-otel-node.git
-    cd elastic-otel-node/packages/mockotlpserver
-    npm ci
+# Install
+
+```
+npm install @elastic/mockotlpserver
+```
 
 # CLI Usage
 
 To use the mock server, (a) start the server then (b) send OTLP data to it.
+The package installs a `mockotlpserver` CLI tool.
 
-    npm start  # or 'node lib/cli.js'
-
-By default it will output received OTLP data using Node.js's `inspect`
-format (used under the hood for `console.log`). This shows the complete
-object structure of the received data. For example, using an example script
-that uses the OpenTelemetry NodeSDK to trace an HTTP request/response:
+```
+npx mockotlpserver
+```
 
-    cd ../../
-    npm run ci-all
-    cd examples/
-    node -r @elastic/opentelemetry-node simple-http-request.js
+By default it will output received OTLP data in two forms:
+
+1. `inspect` format: Uses Node.js's `util.inspect()` (used under the hood for
+   `console.log`). This shows the complete object structure of the received
+   data.
+2. `summary` format: This is a custom text format that attempts to show a
+   brief/relevant summary of the data. This format is currently more refined
+   for *traces* and somewhat for *logs / events*. For metrics, the summary
+   output is poor.
+
+For example, here is the output when receiving telemetry data from a small
+script that creates and HTTP server and makes a single request.
+(This example uses the Elastic Distribution of OpenTelemetry Node.js for
+instrumentation, the upstream OpenTelemetry Node SDK could be used as well.)
+
+```bash
+git clone [email protected]:elastic/elastic-otel-node.git
+cd elastic-otel-node
+npm run ci-all
+cd examples/
+node -r @elastic/opentelemetry-node simple-http-request.js
+```
 
 <details>
-<summary>will yield output close to the following:</summary>
+<summary>mockotlpserver console output</summary>
 
 ```
 % node lib/cli.js
@@ -164,19 +185,25 @@ ExportTraceServiceRequest {
 ------ trace 802356 (2 spans) ------
        span f06b1a "GET" (15.5ms, SPAN_KIND_CLIENT, GET http://localhost:3000/ -> 200)
   +9ms `- span 226bf7 "GET" (4.2ms, SPAN_KIND_SERVER, GET http://localhost:3000/ -> 200)
-
 ```
 
 </details>
 
-It also shows a trace waterfall text representation of received tracing data.
+In particular, note the "trace summary" output that shows a line for each span, showing parent/child relationships:
+
+```
+------ trace 802356 (2 spans) ------
+       span f06b1a "GET" (15.5ms, SPAN_KIND_CLIENT, GET http://localhost:3000/ -> 200)
+  +9ms `- span 226bf7 "GET" (4.2ms, SPAN_KIND_SERVER, GET http://localhost:3000/ -> 200)
+```
 
 
 ## Different OTLP protocols
 
-By default the NodeSDK uses the `OTLP/proto` protocol. The other flavours of OTLP
-are supported by `mockotlpserver` as well. Use the `OTEL_EXPORTER_OTLP_PROTOCOL`
-to tell the NodeSDK to use a different protocol:
+By default the OpenTelemetry JS NodeSDK uses the `OTLP/proto` protocol. The
+other flavours of OTLP are supported by `mockotlpserver` as well. Use the
+`OTEL_EXPORTER_OTLP_PROTOCOL` to tell the NodeSDK to use a different protocol.
+For example:
 
 ```
 cd ../../examples

packages/mockotlpserver/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@elastic/mockotlpserver",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "commonjs",
-  "description": "Elastic OLTP mock server for Node.js",
-  "private": true,
+  "description": "A mock OTLP server, useful for dev and testing",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -13,11 +12,8 @@
   "keywords": [
     "elastic",
     "opentelemetry",
-    "apm",
-    "tracing",
-    "metrics",
-    "logs",
-    "server",
+    "otlp",
+    "testing",
     "mock"
   ],
   "author": "Elastic Observability <https://www.elastic.co/observability>",
@@ -36,6 +32,12 @@
     "example": "cd ../../examples && pwd && node -r @elastic/opentelemetry-node simple-http-request.js",
     "example3": "cd ../../examples && for flav in http/protobuf http/json grpc; do OTEL_EXPORTER_OTLP_PROTOCOL=$flav node -r @elastic/opentelemetry-node simple-http-request.js; done"
   },
+  "files": [
+    "lib",
+    "opentelemetry",
+    "db",
+    "ui"
+  ],
   "main": "lib/index.js",
   "bin": {
     "mockotlpserver": "lib/cli.js"

scripts/github-release.sh

@@ -1,18 +1,22 @@
 #!/usr/bin/env bash
 
-# Create a GitHub release. If the given tag name is the *latest* version, and
-# is not a pre-release, then the GH release will be marked as the latest.
+# Create a GitHub release.
 # (This is typically only run from the release.yml CI workflow.)
 #
-# Usage:
-#   ./scripts/github-release.sh PKG_DIR TAG_NAME
-# Example:
-#   ./scripts/github-release.sh packages/opentelemetry-node v0.1.0
+# The release will be marked as the "latest" if:
+# (a) PKG_DIR is "packages/opentelemetry-node", the primary package in this repo, and
+# (b) the given TAG_NAME is the *latest* "vX.Y.Z" tag, and is not a pre-release.
 #
 # - For auth, this expects the 'GH_TOKEN' envvar to have been set.
 # - The 'TAG_NAME' is typically from the 'GITHUB_REF_NAME' variable
 #   (https://docs.github.com/en/actions/learn-github-actions/variables)
 #   from a GitHub Actions workflow run.
+#
+# Usage:
+#   ./scripts/github-release.sh PKG_DIR TAG_NAME
+# Examples:
+#   ./scripts/github-release.sh packages/opentelemetry-node v0.1.0
+#   ./scripts/github-release.sh packages/mockotlpserver mockotlpserver-v0.2.0
 
 if [ "$TRACE" != "" ]; then
     export PS4='${BASH_SOURCE}:${LINENO}: ${FUNCNAME[0]:+${FUNCNAME[0]}(): }'
@@ -38,10 +42,15 @@ if [[ -z $(git tag -l "${TAG_NAME}") ]]; then
   fatal "invalid TAG_NAME arg: '$TAG_NAME' git tag does not exist"
 fi
 
+PKG_DIR_BASENAME=$(basename "$PKG_DIR")
 PKG_NAME=$($JSON -f "$PKG_DIR/package.json" name)
 PKG_VER=$($JSON -f "$PKG_DIR/package.json" version)
-if [[ "v$PKG_VER" != "$TAG_NAME" ]]; then
-  fatal "TAG_NAME, '$TAG_NAME', does not match version in package.json, '$PKG_VER'"
+EXPECTED_TAG_NAME="v$PKG_VER"
+if [[ "$PKG_DIR" != "packages/opentelemetry-node" ]]; then
+  EXPECTED_TAG_NAME="$(basename "$PKG_DIR")-v$PKG_VER"
+fi
+if [[ "$TAG_NAME" != "$EXPECTED_TAG_NAME" ]]; then
+  fatal "TAG_NAME, '$TAG_NAME', does not match expected value, '$EXPECTED_TAG_NAME'"
 fi
 
 # Extract the changelog section for this version.
@@ -55,13 +64,13 @@ echo
 echo "INFO: List current GitHub releases"
 gh release list
 
+IS_LATEST=false
 # The latest (by semver version ordering) git version tag, excluding pre-releases.
-# TODO: this assumes a tag "vN.M.O", which won't work for prefixed-tags.
 LATEST_GIT_TAG=$(git tag --list --sort=version:refname "v*" | (grep -v - || true) | tail -n1)
-if [[ -z "$LATEST_GIT_TAG" || "$TAG_NAME" == "$LATEST_GIT_TAG" ]]; then
-  IS_LATEST=true
-else
-  IS_LATEST=false
+if [[ "$PKG_DIR" == "packages/opentelemetry-node" ]]; then
+  if [[ -z "$LATEST_GIT_TAG" || "$TAG_NAME" == "$LATEST_GIT_TAG" ]]; then
+    IS_LATEST=true
+  fi
 fi
 
 echo