### Example: Starting and Stopping Monitoring via Multi-Component Action

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/configuration.md

These YAML snippets illustrate how to control the start and stop phases of monitoring for multiple components using `multi_component_action` steps within a test scenario. This is typically done to bracket the period of interest for data collection.

```yaml
- name: Monitor All
  action:
    multi_component_action:
      phase: start_monitoring

- name: Stop Monitoring All
  action:
    multi_component_action:
      phase: stop_monitoring
```

--------------------------------

### Component Configuration Example (YAML)

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/configuration.md

Illustrates the configuration for a 'load-generator' component, detailing its deployment via Docker, execution strategy, and monitoring setup using Prometheus. This YAML snippet shows how to define a component's lifecycle and observability.

```yaml
components:
  load-generator:
    hooks: {}
    configuration: {}
    deployment:
      docker:
        image: load_generator:latest
        network: testbed
        command: ["--serve"]
        environment:
          - OTLP_ENDPOINT=otel-collector:4317
        ports:
          - "5001:5001"
    execution:
      pipeline_perf_loadgen:
        threads: 1
        batch_size: 5000
    monitoring:
      docker_component:
        interval: 1
      prometheus:
        endpoint: http://localhost:5001/metrics
```

--------------------------------

### Dual Exporter Completion Tracking Example

Source: https://github.com/open-telemetry/otel-arrow/blob/main/rust/otap-dataflow/crates/quiver/ARCHITECTURE.md

This example illustrates a setup with a single durable buffer feeding two exporters: a local Parquet writer and a remote OTLP exporter. It details the OTAP Ack/Nack protocol, segment processing, cursor advancement, and progress file updates for reliable data delivery.

```text
Happy-path flow for segment `seg-120` (4 MiB, 3 `RecordBundle`s):

1. Incoming batches append to the WAL and accumulate in the in-memory open
  segment until finalize triggers; then the data is written as `seg-120.arrow`.
1. Quiver enqueues a notification for `parquet_exporter` and `otlp_exporter`.
1. Each exporter drains the segment's three bundles in order and, after
  finishing each bundle, emits `Ack(segment_seq, bundle_index)` (or `Nack`)
  back to Quiver. The consumer-side cursor only advances to the next bundle once the
  acknowledgement for the current bundle is recorded.
1. On each Ack, Quiver updates the subscriber's in-memory progress state.
  The embedding layer periodically calls `maintain()` to flush dirty progress
  files and clean up completed segments. For example, after processing seg-120:

  ```text
  quiver.sub.parquet_exporter:
    oldest_incomplete_segment: 121
    (no segment entries - seg-120 complete)

  quiver.sub.otlp_exporter:
    oldest_incomplete_segment: 121
    (no segment entries - seg-120 complete)
  ```

1. Once every subscriber has acknowledged all bundles in `seg-120` (i.e.,
  `oldest_incomplete_segment > 120` for all subscribers), the segment becomes
  eligible for eviction according to the retention policy.
1. During crash recovery Quiver reads each subscriber's progress file to
  restore per-subscriber state directly--no log replay required.

Nack handling is owned by the embedding layer, not Quiver. When an exporter
returns a NACK, the embedding layer (e.g., durable_buffer_processor):

1. Computes retry delay using its backoff policy
2. Schedules retry via the pipeline's delay mechanism
3. Re-reads the bundle from Quiver when the retry fires
4. Only calls `record_outcome(..., Dropped)` after all retries are exhausted

Quiver's progress files never see transient NACKs, only final outcomes (`Ack`
or `Dropped`). This keeps Quiver decoupled from retry policy decisions.
```

--------------------------------

### Set COLLECTOR environment variable for go install

Source: https://github.com/open-telemetry/otel-arrow/blob/main/collector/examples/README.md

This snippet shows how to set the COLLECTOR environment variable when using the 'go install' method. It specifies the path to the collector binary within the GOPATH.

```shell
COLLECTOR=${GOPATH}/bin/otelarrowcol
```

--------------------------------

### Monitoring Strategy Configuration Example (YAML)

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/plugins/monitoring_strategies.md

Illustrates how to configure different monitoring strategies (Docker, Process, Prometheus) within a YAML file for component deployment and monitoring setup. It shows specific parameters like interval and endpoint.

```yaml
components:
  backend-service:
    deployment:
      docker: ...   # Component should be deployed via docker strategy.
    monitoring:
      docker_component:
        interval: 1
```

```yaml
components:
  backend-service:
    deployment:
      process: ...   # Component should be deployed via process strategy.
    monitoring:
      process_component:
        interval: 1
```

```yaml
components:
  backend-service:
    monitoring:
      prometheus:
        endpoint: http://localhost:8888/metrics
        include:
          - otelcol_exporter_send_failed_log_records_total
          - otelcol_exporter_sent_log_records_total
          - otelcol_process_cpu_seconds_total
```

--------------------------------

### Example: Suite-Level Reporting Hooks (YAML)

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/configuration.md

Illustrates how to define suite-level hooks to run after all scenarios have completed. This example configures 'pipeline_perf_report' and 'process_report' hooks to generate performance and process-level reports based on recorded test events.

```yaml
hooks:
  run:
    post:
      - pipeline_perf_report:
          name: PerfReport - Max Rate
          output:
            - format:
                template: {}
              destination:
                console: {}
          between_events:
            start:
              name: test_framework.test_start
              attributes:
                test.name: Test Max Rate Logs
            end:
              name: test_framework.test_end
              attributes:
                test.name: Test Max Rate Logs

      - process_report:
          name: Process - Max Rate
          components:
            - load-generator
            - otel-collector
            - backend-service
          between_events:
            start:
              name: observation_start
              attributes:
                test.name: Test Max Rate Logs
            end:
              name: observation_stop
              attributes:
                test.name: Test Max Rate Logs
```

--------------------------------

### Python Plugin Metadata Declaration Example

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/plugin_development.md

Shows how to define `PLUGIN_META` for a plugin, specifying supported contexts, installed hooks, and an example YAML usage. This metadata is crucial for documentation, validation, and CLI configuration.

```python
from ....runner.registry import PluginMeta
from ....core.context import FrameworkElementHookContext, ComponentHookContext

PLUGIN_META = PluginMeta(
    supported_contexts=[FrameworkElementHookContext.__name__, ComponentHookContext.__name__],
    installs_hooks=[],
    yaml_example="""
steps:
  - action:
      wait:
        delay_seconds: 10
    hooks:
      run:
        pre:
          - run_command:
              command: python somefile.py
""")
```

--------------------------------

### Install otelarrowcol using go install (Golang)

Source: https://github.com/open-telemetry/otel-arrow/blob/main/collector/BUILDING.md

Installs the latest release of otelarrowcol using the 'go install' command. This downloads the sources and builds the executable, making it available in the system's PATH. This is a convenient way to install a collector from remote sources.

```shell
go install github.com/open-telemetry/otel-arrow/collector/cmd/otelarrowcol
otelarrowcol --config <path-to-config.yaml>
```

--------------------------------

### Start Collectors with Configuration Files

Source: https://github.com/open-telemetry/otel-arrow/blob/main/collector/examples/shutdown/README.md

This snippet shows how to start three OpenTelemetry collectors using specified YAML configuration files. It assumes the `$COLLECTOR` environment variable is set to the collector executable. No specific inputs or outputs are defined, but it's a prerequisite for the shutdown test.

```shell
$COLLECTOR --config saas-collector.yaml
$COLLECTOR --config middle-collector.yaml
$COLLECTOR --config edge-collector.yaml
```

--------------------------------

### Docker Deployment Configuration Example

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/configuration.md

This YAML snippet demonstrates how to configure a Docker deployment strategy for a component. It specifies the Docker image, network, command, environment variables, and port mappings. This configuration is used by the orchestrator during the 'deploy' phase to launch the container.

```yaml
components:
  load-generator:
    deployment:
      docker:
        image: load_generator:latest
        network: testbed
        command: ["--serve"]
        environment:
          - OTLP_ENDPOINT=otel-collector:4317
        ports:
          - "5001:5001"
```

--------------------------------

### Example: Multiple Monitoring Strategies Configuration

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/configuration.md

This YAML configuration demonstrates how to define multiple monitoring strategies for a single component. It includes polling Docker stats and scraping metrics from a Prometheus endpoint, allowing for comprehensive observation of component behavior.

```yaml
components:
  load-generator:
    monitoring:
      docker_component:
        interval: 1
      prometheus:
        endpoint: http://localhost:5001/metrics
```

--------------------------------

### Run Data Replay Collector

Source: https://github.com/open-telemetry/otel-arrow/blob/main/collector/examples/recorder/README.md

This command starts the OpenTelemetry collector to replay previously recorded data through an Arrow pipeline. It requires a replay configuration file (replay.yaml) and uses the data recorded in the first step.

```shell
$COLLECTOR --config replay.yaml
```

--------------------------------

### Run Data Recorder Collector

Source: https://github.com/open-telemetry/otel-arrow/blob/main/collector/examples/recorder/README.md

This command starts the OpenTelemetry collector to record incoming data. It requires a configuration file (target.yaml) and sets environment variables for the operating system and architecture. The recorded data is saved to JSON files.

```shell
COLLECTOR --config target.yaml
```

--------------------------------

### Run OTLP Bridge Exporting Side (Shell)

Source: https://github.com/open-telemetry/otel-arrow/blob/main/collector/examples/metadata-bridge/README.md

This command starts the OpenTelemetry Collector in its role as the exporting side of the bridge. It requires a configuration file named 'edge-collector.yaml' to be present in the current directory. The collector will then process and export telemetry data.

```shell
$COLLECTOR --config edge-collector.yaml
```

--------------------------------

### Run Parquet Query Examples

Source: https://github.com/open-telemetry/otel-arrow/blob/main/rust/parquet-query-examples/README.md

This command executes the example queries against the generated OTAP Parquet data. It requires the 'parquet-query-examples' package to be built and run. The output will be the results of the executed queries.

```shell
cargo run --package parquet-query-examples --example query_logs
```

--------------------------------

### Example Plugin Registration Summary (Python)

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/plugin_development.md

Provides a consolidated example of registering both the configuration and implementation classes for a plugin named 'run_command'. This illustrates the best practice of using the same type name for both components and adjacent decorator placement.

```python
from ....core.strategies.hook_strategy import HookStrategy, HookStrategyConfig
from ....runner.registry import hook_registry

@hook_registry.register_config("run_command")
class RunCommandConfig(HookStrategyConfig):
    command: str

@hook_registry.register_class("run_command")
class RunCommandHook(HookStrategy):
    def __init__(self, config: RunCommandConfig):
        self.config = config

    def execute(self, ctx):
        #...
```

--------------------------------

### Python Plugin Initialization Example

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/plugin_development.md

Demonstrates how to initialize a plugin class by inheriting from a base strategy and accepting a configuration object in the constructor. The configuration instance is stored for later use during plugin execution.

```python
class RunCommandHook(HookStrategy):
    def __init__(self, config: RunCommandConfig):
        self.config = config
```

--------------------------------

### Basic TLS Receiver and Exporter Configuration

Source: https://github.com/open-telemetry/otel-arrow/blob/main/docs/tls-configuration-guide.md

Example demonstrating a basic setup with a TLS-enabled OTLP receiver and a TLS-enabled OTLP exporter. The receiver uses its own certificate and key, while the exporter trusts a custom CA certificate. This configuration is suitable for secure data ingestion and forwarding.

```yaml
receivers:
  otlp:
    config:
      listening_addr: "0.0.0.0:4319"
      tls:
        cert_file: "/etc/certs/receiver-server.crt"
        key_file: "/etc/certs/receiver-server.key"

exporters:
  otlp:
    config:
      grpc_endpoint: "https://upstream-collector:4317"
      tls:
        ca_file: "/etc/certs/upstream-ca.crt"
```

--------------------------------

### Plugin Registration Example (Python)

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/plugin_development.md

Illustrates the standard pattern for registering both the configuration and implementation classes of a plugin using decorators provided by a specific registry. The string identifier used in registration ('my_strategy') serves as the key for referencing the plugin in configuration.

```python
# Register the config class with its YAML type name
@execution_registry.register_config("my_strategy")
class MyStrategyConfig(ExecutionStrategyConfig):
    ...

# Register the implementation class with the same type name
@execution_registry.register_class("my_strategy")
class MyStrategy(ExecutionStrategy):
    ...

```

--------------------------------

### Example: Defining Event-Based Time Windows for Monitoring Data

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/configuration.md

This YAML configuration shows how to define time windows for analyzing monitoring data based on specific events. The `between_events` block specifies start and end events, allowing for focused reporting on particular phases of a test.

```yaml
between_events:
  start:
    name: observation_start
    attributes:
      test.name: Test Max Rate Logs
  end:
    name: observation_stop
    attributes:
      test.name: Test Max Rate Logs
```

--------------------------------

### Example Hook Plugin Implementation (Python)

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/plugin_development.md

Demonstrates the implementation of a 'run_command' hook plugin. It includes the configuration class inheriting from HookStrategyConfig and the implementation class inheriting from HookStrategy, along with the necessary registration decorators and the execute method.

```python
from ....core.strategies.hook_strategy import HookStrategy, HookStrategyConfig
from ....runner.registry import hook_registry, PluginMeta

@hook_registry.register_config("run_command")
class RunCommandConfig(HookStrategyConfig):
    command: str  # Shell command to execute

@hook_registry.register_class("run_command")
class RunCommandHook(HookStrategy):
    PLUGIN_META = PluginMeta(
        supported_contexts=["FrameworkElementHookContext", "ComponentHookContext"],
        installs_hooks=[],
        yaml_example="""
hooks:
  run:
    pre:
      - run_command:
          command: echo 'Hello'
"""
    )

    def __init__(self, config: RunCommandConfig):
        self.config = config

    def execute(self, ctx: BaseContext):
        import subprocess
        logger = ctx.get_logger(__name__)
        logger.debug(f"Executing: {self.config.command}")
        subprocess.run([self.config.command], shell=True, check=True)

```

--------------------------------

### Define a Single Component Start Step (YAML)

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/configuration.md

This YAML defines a test step named 'Start Load Generator'. It uses 'component_action' to execute the 'start' phase on the 'load-generator' component, initiating its primary execution strategy.

```yaml
- name: Start Load Generator
  action:
    component_action:
      phase: start
      target: load-generator

```

--------------------------------

### Setup Virtual Environment and Install Dependencies

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/test_suites/integration/README.md

Sets up a Python virtual environment and installs the necessary dependencies for the orchestrator script. This is a prerequisite for running the test suites and should be performed in the 'otel-arrow/tools/pipeline_perf_test' directory.

```shell
# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r orchestrator/requirements.txt
```

--------------------------------

### Batch Processor Configuration Examples (YAML)

Source: https://github.com/open-telemetry/otel-arrow/blob/main/collector/processor/concurrentbatchprocessor/README.md

Demonstrates two common configurations for the batch processor. The first configures a default batch processor and a second with custom buffer size and timeout. The second example shows how to enforce a maximum batch size without artificial delays.

```yaml
processors:
  batch:
  batch/2:
    send_batch_size: 10000
    timeout: 10s
```

```yaml
processors:
  batch:
    send_batch_max_size: 10000
    timeout: 0s
```

--------------------------------

### Start df_engine with OTLP Receiver for Testing

Source: https://github.com/open-telemetry/otel-arrow/blob/main/rust/otap-dataflow/crates/otap/src/experimental/azure_monitor_exporter/README.md

Starts the df_engine with a specific configuration file designed for testing the Azure Monitor Exporter with an OTLP receiver. This setup allows for sending test data to the exporter.

```bash
./target/release/df_engine \
  --pipeline crates/otap/src/experimental/azure_monitor_exporter/otlp-ame.yaml \
  --num-cores 1
```

--------------------------------

### Build Docker Images Configuration Example (YAML)

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/plugins/hook_strategies.md

Provides an example of how to configure the `build_docker_images` hook strategy in a YAML file. This configuration specifies which components to build Docker images for and whether to log the build process. It's used to control the pre-execution steps in a pipeline.

```yaml
hooks:
  run:
    pre:
      - build_docker_images:
          components:
            - load-generator
            - backend-service
          log_build: false

```

--------------------------------

### NO_PROXY Pattern Examples

Source: https://github.com/open-telemetry/otel-arrow/blob/main/rust/otap-dataflow/docs/proxy-support.md

Demonstrates various NO_PROXY patterns for bypassing proxy settings, including wildcard, exact hostname, domain suffix, IP addresses, CIDR notation, and host with port specifications. The example shows a typical NO_PROXY environment variable setting.

```bash
NO_PROXY="localhost,*.internal,192.168.0.0/16,10.0.0.0/8,example.com:8080"
```

--------------------------------

### Test Step to Start Load Generator

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/configuration.md

This YAML snippet defines a test step that initiates the execution strategy of a specific component, in this case, the 'load-generator'. The 'component_action' targets the 'load-generator' and specifies the 'start' phase, causing the orchestrator to invoke the configured execution strategy.

```yaml
- name: Start Load Generator
  action:
    component_action:
      phase: start
      target: load-generator
```

--------------------------------

### Python Plugin Registration Example

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/plugin_development.md

Illustrates how to register a custom plugin class with the framework's plugin system using a registry decorator. The decorator associates a unique name ('run_command') with the plugin implementation.

```python
from ....runner.registry import hook_registry

@hook_registry.register_class("run_command")
class RunCommandHook(HookStrategy):
    ...
```

--------------------------------

### Shell Example: Plugin Test Directory Structure

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/plugin_development.md

Illustrates the conventional directory structure for testing plugins within the OpenTelemetry OTel-Arrow framework. It shows how a plugin file located in `lib/impl/strategies/hooks/` should have its corresponding test file in `tests/impl/strategies/hooks/`.

```shell
lib/impl/strategies/hooks/raise_exception.py

# Corresponding test file:
tests/impl/strategies/hooks/test_raise_exception.py
```

--------------------------------

### Process Deployment Strategy Example (YAML)

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/plugins/deployment_strategies.md

Example YAML configuration for deploying a component using the process strategy. This specifies the command to execute and environment variables for the process.

```yaml
components:
  otel-collector:
    deployment:
      process:
        command: python -m ./load_generator/loadgen.py --serve
        environment: {}
```

--------------------------------

### Set COLLECTOR environment variable for Golang toolchain

Source: https://github.com/open-telemetry/otel-arrow/blob/main/collector/examples/README.md

This snippet demonstrates how to set the COLLECTOR environment variable when using an installed Golang toolchain and local sources. It points to the compiled collector binary in the relative path.

```shell
COLLECTOR=../../../bin/otelarrowcol
```

--------------------------------

### Docker Deployment Strategy Example (YAML)

Source: https://github.com/open-telemetry/otel-arrow/blob/main/tools/pipeline_perf_test/orchestrator/docs/plugins/deployment_strategies.md

Example YAML configuration for deploying a component using the Docker strategy. This specifies the Docker image, network settings, volume mounts, command to run, and port mappings.

```yaml
components:
  otel-collector:
    deployment:
      docker:
        image: otel/opentelemetry-collector:latest
        network: testbed
        volumes:
          - ./system_under_test/otel-collector/collector-config-with-batch-processor.yaml:/etc/otel/collector-config.yaml:ro
        command: ["--config", "/etc/otel/collector-config.yaml"]
        ports:
          - "8888:8888"
```

--------------------------------

### Example Trace Structure in Text Format

Source: https://github.com/open-telemetry/otel-arrow/blob/main/rust/otap-dataflow/docs/telemetry/tracing-draft-not-for-review.md

Illustrates a sample trace structure for a batch, detailing spans, events, and their associated attributes. This format helps in understanding the flow and processing steps within the OTel-Arrow system.

```text
Trace: batch-1234
  +- [Span] receiver/otlp/rcv-1
     Events: control/ack, out_port=main, channel_queue_depth=2
     |
     +- [Span] processor/batch/proc-2
        Events: batch_flush, backpressure, control/timer_tick
        |
        +- [Span] exporter/http/exp-1
           Events: export_success, control/shutdown
```

--------------------------------

### Test mTLS Connection with OpenSSL

Source: https://github.com/open-telemetry/otel-arrow/blob/main/docs/tls-configuration-guide.md

Tests a mutual TLS (mTLS) connection by providing both a client certificate and its corresponding private key, along with the CA certificate for verification. This is essential for debugging client authentication issues in mTLS setups.

```bash
# Test mTLS connection with client certificate
openssl s_client -connect localhost:4319 \
  -cert /path/to/client.crt \
  -key /path/to/client.key \
  -CAfile /path/to/ca.crt
```