From 6c9a840372137166a3fe86e6fb4923a1729a26c0 Mon Sep 17 00:00:00 2001
From: Martin Kuba <martin@martinkuba.com>
Date: Wed, 27 Sep 2023 17:22:26 -0700
Subject: [PATCH] docs: added performance benchmarking doc

---
 CHANGELOG.md                        |  2 ++
 doc/contributing/benchmark-tests.md | 53 +++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)
 create mode 100644 doc/contributing/benchmark-tests.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f8a0051fab..5a330b09e7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,8 @@ For experimental package changes, see the [experimental CHANGELOG](experimental/
 
 ### :books: (Refine Doc)
 
+* docs(contributing): added guidelines for adding benchmark tests [#4169](https://github.com/open-telemetry/opentelemetry-js/pull/4169)
+
 ### :house: (Internal)
 
 * test: added a performance benchmark test for span creation [#4105](https://github.com/open-telemetry/opentelemetry-js/pull/4105)
diff --git a/doc/contributing/benchmark-tests.md b/doc/contributing/benchmark-tests.md
new file mode 100644
index 0000000000..141475eccb
--- /dev/null
+++ b/doc/contributing/benchmark-tests.md
@@ -0,0 +1,53 @@
+
+# Performance Benchmark Testing Guide
+
+Benchmark tests are intended to measure performance of small units of code.
+
+It is recommended that operations that have a high impact on the performance of the SDK (or potential for) are accompanied by a benchmark test. This helps end-users understand the performance trend over time, and it also helps maintainers catch performance regressions.
+
+Benchmark tests are run automatically with every release, and the results are available at <https://open-telemetry.github.io/opentelemetry-js/benchmark>.
+
+## Running benchmark tests
+
+Performance benchmark tests can be run from the root for all modules or from a single module directory only for that module:
+
+``` bash
+# benchmark all modules
+npm run test:bench
+
+# benchmark a single module
+cd packages/opentelemetry-sdk-trace-base
+npm run test:bench
+```
+
+## Adding a benchmark test
+
+Unlike unit tests, benchmark tests should be written in plain JavaScript (not Typescript).
+
+Add a new test file in folder `test/performance/benchmark` using the following as a template:
+
+``` javascript
+const Benchmark = require('benchmark');
+
+const suite = new Benchmark.Suite();
+
+suite.on('cycle', event => {
+  console.log(String(event.target));
+});
+
+suite.add('new benchmark test', function() {
+ // write code to test ...
+});
+
+suite.run();
+```
+
+## Automatically running benchmark tests
+
+If you want your test to run automatically with every release (to track trend over time), register the new test file by requiring it in `test/performance/benchmark/index.js`.
+
+Add the `test:bench` script in package.json, if the module does not contain.
+
+``` json
+"test:bench": "node test/performance/benchmark/index.js"
+```