Add Performance and Blocking specification

specification/library-guidelines.md

@@ -74,8 +74,13 @@ Note that mocking is also possible by using the SDK and a Mock Exporter without
 
 The mocking approach chosen will depend on the testing goals and at which point exactly it is desirable to intercept the telemetry data path during the test.
 
+## Performance and Blocking
+
+See the [Performance and Blocking](performance.md) specification for
+guidelines on the performance expectations that API implementations should meet, strategies for meeting these expectations, and a description of how implementations should document their behavior under load.
+
 ## Concurrency and Thread-Safety
 
-See [Concurrency and Thread-Safety](concurrency.md) specification for
+See the [Concurrency and Thread-Safety](concurrency.md) specification for
 guidelines on what concurrency safeties should API implementations provide
 and how they should be documented.

specification/performance.md

@@ -0,0 +1,49 @@
+# Performance and Blocking of OpenTelemetry API
+
+This document defines common principles that will help designers create language libraries that are safe to use. 
+
+## Key principles
+
+Here are the key principles:
+
+- **Library should not block end-user application by default.**
+- **Library should not consume unbounded memory resource.**
+
+Although there are inevitable overhead to achieve monitoring, API should not degrade the end-user application as possible. So that it should not block the end-user application nor consume too much memory resource.
+
+Especially, most telemetry exporters need to call API of servers to export traces. API call operations should be performed in asynchronous I/O or background thread to prevent blocking end-user applications.
+
+See also [Concurrency and Thread-Safety](concurrency.md) if the implementation supports concurrency.
+
+### Tradeoff between non-blocking and memory consumption
+
+Incomplete asynchronous I/O tasks or background tasks may consume memory to preserve their state. In such a case, there is a tradeoff between dropping some tasks to prevent memory starvation and keeping all tasks to prevent information loss.
+
+If there is such tradeoff in language library, it should provide the following options to end-user:
+
+- **Prevent blocking**: Dropping some information under overwhelming load and show warning log to inform when information loss starts and when recovered
+  - Should be a default option other than Logging
+  - Should provide option to change threshold of the dropping
+  - Better to provide metric that represents effective sampling ratio
+  - Language library might provide this option for Logging
+- **Prevent information loss**: Preserve all information but possible to consume many resources
+  - Should be a default option for Logging
+  - Language library might provide this option also for Tracing and Metrics
+
+### End-user application should aware of the size of logs
+
+Logging could consume much memory by default if the end-user application emits too many logs. This default behavior is intended to preserve logs rather than dropping it. To make resource usage bounded, the end-user should consider reducing logs that are passed to the exporters.
+
+Therefore, the language library should provide a way to filter logs to capture by OpenTelemetry. End-user applications may want to log so much into log file or stdout (or somewhere else) but not want to send all of the logs to OpenTelemetry exporters.
+
+In a documentation of the language library, it is a good idea to point out that too many logs consume many resources by default then guide how to filter logs.
+
+### Shutdown and explicit flushing could block
+
+The language library could block the end-user application when it shut down. On shutdown, it has to flush data to prevent information loss. The language library should support user-configurable timeout if it blocks on shut down.
+
+If the language library supports an explicit flush operation, it could block also.
+
+## Documentation
+
+If language specific implementation has special characteristics that are not described in this document, such characteristics should be documented.