From 3654415da191844f51ba14b46a7833e3bf498abf 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

---
 doc/contributing/benchmark-tests.md | 55 +++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 doc/contributing/benchmark-tests.md

diff --git a/doc/contributing/benchmark-tests.md b/doc/contributing/benchmark-tests.md
new file mode 100644
index 00000000000..3e4e85480a1
--- /dev/null
+++ b/doc/contributing/benchmark-tests.md
@@ -0,0 +1,55 @@
+
+# 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`.
+
+Use 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"
+```