From e24210dc483b98a0d9f62917878dd4234a43aa4c Mon Sep 17 00:00:00 2001 From: Joe Sirianni Date: Mon, 10 Nov 2025 15:21:28 -0500 Subject: [PATCH 1/4] feat: Website --- .github/workflows/pages.yml | 61 ++++++++++++ docs/Gemfile | 6 ++ docs/README.md | 29 ++++++ docs/_config.yml | 22 +++++ docs/index.md | 180 ++++++++++++++++++++++++++++++++++++ 5 files changed, 298 insertions(+) create mode 100644 .github/workflows/pages.yml create mode 100644 docs/Gemfile create mode 100644 docs/README.md create mode 100644 docs/_config.yml create mode 100644 docs/index.md diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..b22006f --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,61 @@ +name: Deploy GitHub Pages + +on: + push: + branches: + - main + paths: + - 'README.md' + - 'docs/**' + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Setup Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: '3.1' + bundler-cache: true + + - name: Setup Pages + id: pages + uses: actions/configure-pages@v5 + + - name: Build with Jekyll + run: | + cd docs + bundle install + bundle exec jekyll build -d ../_site + env: + JEKYLL_ENV: production + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: _site + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 + diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 0000000..311fe9c --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,6 @@ +source "https://rubygems.org" + +gem "jekyll", "~> 4.3" +gem "jekyll-theme-minimal" +gem "jekyll-relative-links" + diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..8a0555d --- /dev/null +++ b/docs/README.md @@ -0,0 +1,29 @@ +# Blitz Documentation + +This directory contains the documentation for Blitz, which is automatically built and deployed to GitHub Pages. + +## Local Development + +To preview the documentation locally using Jekyll: + +```bash +cd docs +bundle install +bundle exec jekyll serve +``` + +Then open [http://localhost:4000](http://localhost:4000) in your browser. + +## GitHub Pages Setup + +The documentation is automatically deployed to GitHub Pages via the `.github/workflows/pages.yml` workflow. + +To enable GitHub Pages: + +1. Go to your repository settings on GitHub +2. Navigate to "Pages" in the left sidebar +3. Under "Source", select "GitHub Actions" +4. The site will be automatically built and deployed when changes are pushed to the `main` branch + +The site will be available at: `https://observiq.github.io/blitz/` + diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..6d2452b --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,22 @@ +title: Blitz Documentation +description: A load generation tool for Bindplane managed collectors +theme: jekyll-theme-minimal +plugins: + - jekyll-relative-links +relative_links: + enabled: true + collections: true +include: + - generator + - output + - release + - man +exclude: + - Gemfile + - Gemfile.lock + - node_modules + - vendor/bundle/ + - vendor/cache/ + - vendor/gems/ + - vendor/ruby/ + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..3fef624 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,180 @@ +--- +layout: default +--- + +
+ Blitz +
+ +# Blitz + +A load generation tool for Bindplane managed collectors. + +## Documentation + +- [Configuration Guide](configuration.md) - Complete guide to configuring blitz with YAML files, environment variables, and command-line flags +- [Architecture Overview](architecture.md) - Detailed explanation of the application architecture, components, and data flow +- [Metrics Documentation](metrics.md) - Comprehensive guide to monitoring and metrics exposed by blitz +- [Shell Completion](shell-completion.md) - Guide to installing and using shell autocompletion for bash, zsh, fish, and PowerShell +- [Development Guide](development.md) - Guidelines for contributing to the project +- [Contributing Guidelines](CONTRIBUTING.md) - How to contribute to the project + +## Components + +Blitz consists of generators that create log data and outputs that send data to destinations. + +### Generators + +- **[nop](generator/nop.md)** - No operation generator for testing infrastructure without generating data +- **[json](generator/json.md)** - Generates structured JSON logs +- **[winevt](generator/winevt.md)** - Generates Windows Event logs in unparsed XML format +- **[palo-alto](generator/palo-alto.md)** - Generates realistic Palo Alto firewall syslog entries +- **[apache-common](generator/apache-common.md)** - Generates Apache Common Log Format (CLF) entries +- **[apache-combined](generator/apache-combined.md)** - Generates Apache Combined Log Format entries with referer and user-agent +- **[apache-error](generator/apache-error.md)** - Generates Apache Error Log Format entries for server diagnostics +- **[nginx](generator/nginx.md)** - Generates NGINX Combined Log Format entries matching NGINX's default log format +- **[postgres](generator/postgres.md)** - Generates PostgreSQL log format entries including query logs, connections, and database events + +### Outputs + +- **[nop](output/nop.md)** - No operation output for testing infrastructure without sending data +- **[stdout](output/stdout.md)** - Writes logs to standard output for debugging and testing +- **[tcp](output/tcp.md)** - Sends logs over TCP connections with optional TLS encryption +- **[udp](output/udp.md)** - Sends logs over UDP connections +- **[syslog](output/syslog.md)** - Formats and sends logs via syslog (RFC 3164 or 5424) over UDP or TCP +- **[otlp-grpc](output/otlp-grpc.md)** - Sends logs via OpenTelemetry Protocol (OTLP) over gRPC +- **[file](output/file.md)** - Writes logs to files with automatic rotation and compression + +## Installation + +Blitz supports the following platforms: +- **Operating Systems**: Linux, macOS (Darwin), Windows, FreeBSD +- **CPU Architectures**: amd64 (x86_64), arm64 + +If your platform is not listed above, please [open an issue](https://github.com/observiq/blitz/issues) +and we'll do our best to add support for it. + +### CLI + +Download the binary for your platform from the [latest release](https://github.com/observiq/blitz/releases/latest): + +Extract the archive and run the binary directly in a terminal: + +```bash +tar -xzf blitz_*_linux_amd64.tar.gz +``` + +Run with default NOP configuration: + +```bash +./blitz +``` + +Run with JSON generator and TCP output: + +```bash +./blitz \ + --generator-type json \ + --generator-json-workers 2 \ + --generator-json-rate 500ms \ + --output-type tcp \ + --output-tcp-host logs.example.com \ + --output-tcp-port 9090 \ + --output-tcp-workers 3 \ + --logging-level info +``` + +### Linux Systemd Service + +Download the appropriate package for your Linux distribution from the [latest release](https://github.com/observiq/blitz/releases/latest): + +- **Debian/Ubuntu**: `blitz_amd64.deb` or `blitz_arm64.deb` +- **Red Hat/CentOS/Fedora**: `blitz_amd64.rpm` or `blitz_arm64.rpm` + +Install the package with your package manager: + +**Debian** + +```bash +sudo apt-get install -f ./blitz_amd64.deb +``` + +**RHEL** + +```bash +sudo dnf install ./blitz_amd64.rpm +``` + +Edit the configuration file: + +```bash +sudo vi /etc/blitz/config.yaml +``` + +Example minimal configuration for JSON generator and TCP output: + +```yaml +generator: + type: json + json: + workers: 2 + rate: 500ms +output: + type: tcp + tcp: + host: logs.example.com + port: 9090 + workers: 3 +logging: + level: info +``` + +Enable and start the service + +```bash +sudo systemctl enable blitz +sudo systemctl start blitz +sudo systemctl status blitz +``` + +View service logs: + +```bash +sudo journalctl -u blitz -f +``` + +### Container + +Pull the Docker image from GitHub Container Registry and run it with environment variables for configuration: + +Run with default NOP configuration: + +```bash +docker run --rm ghcr.io/observiq/blitz:latest +``` + +Run with JSON generator and TCP output: + +```bash +docker run --rm \ + -e BINDPLANE_GENERATOR_TYPE=json \ + -e BINDPLANE_GENERATOR_JSON_WORKERS=2 \ + -e BINDPLANE_GENERATOR_JSON_RATE=500ms \ + -e BINDPLANE_OUTPUT_TYPE=tcp \ + -e BINDPLANE_OUTPUT_TCP_HOST=logs.example.com \ + -e BINDPLANE_OUTPUT_TCP_PORT=9090 \ + -e BINDPLANE_OUTPUT_TCP_WORKERS=3 \ + -e BINDPLANE_LOGGING_LEVEL=info \ + ghcr.io/observiq/blitz:latest +``` + +For detailed configuration options, see the [Configuration Guide](configuration.md). + +## Community + +The Blitz is an open source project. If you'd like to contribute, take a look at our [contribution guidelines](CONTRIBUTING.md) and [developer guide](development.md). We look forward to building with you. + +## Similar Tools + +- [flog](https://github.com/mingrammer/flog) - A fake log generator for common log formats + From f9574e623b2e4dafe1a10c7b2bf865c473711834 Mon Sep 17 00:00:00 2001 From: Joe Sirianni Date: Mon, 10 Nov 2025 15:26:09 -0500 Subject: [PATCH 2/4] run on pr --- .github/workflows/pages.yml | 11 +++++++---- docs/README.md | 25 ++++++++++++++++++++++++- 2 files changed, 31 insertions(+), 5 deletions(-) diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index b22006f..9cdb4a6 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -2,8 +2,10 @@ name: Deploy GitHub Pages on: push: - branches: - - main + paths: + - 'README.md' + - 'docs/**' + pull_request: paths: - 'README.md' - 'docs/**' @@ -15,7 +17,7 @@ permissions: id-token: write concurrency: - group: "pages" + group: "pages-${{ github.ref }}" cancel-in-progress: false jobs: @@ -50,10 +52,11 @@ jobs: deploy: environment: - name: github-pages + name: ${{ github.ref == 'refs/heads/main' && 'github-pages' || 'github-pages-preview' }} url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest needs: build + if: github.event_name != 'pull_request' || github.event.action != 'closed' steps: - name: Deploy to GitHub Pages id: deployment diff --git a/docs/README.md b/docs/README.md index 8a0555d..2985aa7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -25,5 +25,28 @@ To enable GitHub Pages: 3. Under "Source", select "GitHub Actions" 4. The site will be automatically built and deployed when changes are pushed to the `main` branch -The site will be available at: `https://observiq.github.io/blitz/` +The production site will be available at: `https://observiq.github.io/blitz/` + +## Testing on Branches + +You can test documentation changes on branches before merging to `main`: + +### Pull Request Previews + +When you open a pull request that modifies documentation files: +- The workflow automatically builds and deploys a preview +- A preview URL will be posted as a comment on the PR +- The preview is available for review before merging + +### Branch Testing + +When you push changes to any branch (not just `main`): +- The workflow builds the site +- For non-main branches, it deploys to a preview environment +- You can view the preview URL in the workflow run summary + +This allows you to: +- Test documentation changes in isolation +- Share preview links with reviewers +- Verify links and formatting before merging From 46eb42a35a466f2c3c0337ed91c3f12ad3ce8cbe Mon Sep 17 00:00:00 2001 From: Joe Sirianni Date: Mon, 10 Nov 2025 15:33:43 -0500 Subject: [PATCH 3/4] ci From a6da8f6c8c6be2f3cb9d8d7bd9d0b08b8bcd3e40 Mon Sep 17 00:00:00 2001 From: Joe Sirianni Date: Mon, 10 Nov 2025 15:35:14 -0500 Subject: [PATCH 4/4] ci