Create a local development guide

[VinozzZ]

When a new contributor is getting started on the project, it would be helpful to have a document that goes through development workflow for Refinery. Some of the topics that this document can cover:

• How to run Refinery locally
• How to run tests
• How to send test traffic to a local instance of Refinery

[mterhar]

The setup below is what I used to build and test link-awareness. It requires multiple refinery nodes to be running and some data flowing through them. I put all of these files in a subdirectory within the refinery repo and .gitignored it.

docker-compose.yml file will build and run 2 refineries and a redis

services:
  refinery1:
    build: ../
    ports:
      - 4317:4317
      - 8080:8080
    entrypoint:
      - "refinery"
    command:
      - "-c"
      - "/etc/refinery/config.yaml"
      - "-r"
      - "/etc/refinery/rules.yaml"
    volumes:
      - ./config.yaml:/etc/refinery/config.yaml
      - ./rules.yaml:/etc/refinery/rules.yaml
  refinery2:
    build: ../
    ports:
      - 4817:4317
      - 8880:8080
    entrypoint:
      - "refinery"
    command:
      - "-c"
      - "/etc/refinery/config.yaml"
      - "-r"
      - "/etc/refinery/rules.yaml"
    volumes:
      - ./config.yaml:/etc/refinery/config.yaml
      - ./rules.yaml:/etc/refinery/rules.yaml
  redis:
    image: redis:6.2.5
    expose:
      - "6379"

Using the otel-go-batch example, we'll create a bunch of traffic that has span links.

Config.yaml

General:
  ConfigurationVersion: 2
  MinRefineryVersion: v2.0
Network:
  ListenAddr: "0.0.0.0:8080"
  PeerListenAddr: "0.0.0.0:8081"
RefineryTelemetry:
  AddRuleReasonToTrace: true
  AddSpanCountToRoot: true
  AddHostMetadataToTrace: true
IDFields:
  TraceNames: [ trace.trace_id ]
  ParentNames: [ trace.parent_id ]
  LinkNames: [ trace.link.trace_id ]
Debugging:
  QueryAuthToken: sneaky-longer-token
  AdditionalErrorFields:
    - trace.span_id
  DryRun: true
Logger:
  Type: honeycomb
  Level: debug
HoneycombLogger:
  APIKey: $REFINERY_APIKEY
  Dataset: refinery-logs
LegacyMetrics:
  Enabled: true
  APIKey: $REFINERY_APIKEY
  Dataset: refinery-metrics
  ReportingInterval: 20s
OTelMetrics:
  Enabled: false
PeerManagement:
  Type: redis
  IdentifierInterfaceName: eth0
RedisPeerManagement:
  Host: redis:6379
Collection:
  MaxAlloc: 6Gb
Specialized:
  AdditionalAttributes:
    ClusterName: homelab
GRPCServerParameters:
  Enabled: true
  ListenAddr: "0.0.0.0:4317"
StressRelief:
  Mode: monitor
  ActivationLevel: 90
  DeactivationLevel: 70
  SamplingRate: 300

Rules.yaml

RulesVersion: 2
Samplers:
  __default__:
    RulesBasedSampler:
      Rules:
        - Name: drop jobs
          Drop: true
          Conditions:
            - Field: job.emitted_by
              Operator: =
              Value: worker
        - Name: keep scheduler
          SampleRate: 1
          Conditions:
            - Field: name
              Operator: =
              Value: "Evaluate the queue and environment"
        - Name: Everything else 
          SampleRate: 1

Whenever I made a change to the local code, I'd run docker compose up --build and it'd take about 40 seconds to rebuild the container and then run it.

In another terminal I do a go run . in the otel-batch-go repo directory and then check the honeycomb UI for the Logs, Metrics, and Trace data that I expect.

[fchikwekwe]

This ticket is standing work to improve Refinery development docs. It won't block release so I'm removing it from 2.4 milestone.