Merge branch 'main' into main

Author: FuzzysTodd

.cursor/rules/development-workflow.mdc

@@ -0,0 +1,95 @@
+---
+description: Development workflow, commands, and commit guidelines for Pyroscope
+globs:
+alwaysApply: false
+---
+
+# Development Workflow
+
+## Prerequisites
+
+- Go 1.24+
+- Docker
+- Node v18
+- Yarn v1.22
+- All other tools auto-download to `.tmp/bin/`
+
+## Build Commands
+
+```bash
+# Build backend
+make go/bin
+
+# Run Go tests
+make go/test
+
+# Build frontend
+yarn install
+yarn dev          # Dev server on :4041
+
+# Run backend for frontend development
+yarn backend:dev  # Runs Pyroscope server
+
+# Docker image
+make GOOS=linux GOARCH=amd64 docker-image/pyroscope/build
+```
+
+## Running Locally
+
+```bash
+# Run all components in monolithic mode with embedded Grafana
+go run ./cmd/pyroscope --target all,embedded-grafana
+# Pyroscope: http://localhost:4040
+# Grafana: http://localhost:4041
+```
+
+## Code Generation
+
+**CRITICAL**: After changing protobuf, configs, or flags:
+
+```bash
+make generate
+```
+
+Commit the generated files with your changes.
+
+## Useful Make Targets
+
+```bash
+make help              # Show all available targets
+make lint              # Run linters
+make go/test           # Run Go unit tests
+make go/bin            # Build binaries
+make go/mod            # Tidy go modules
+make generate          # Generate code (protobuf, mocks, etc.)
+make docker-image/pyroscope/build  # Build Docker image
+```
+
+## Commit Guidelines
+
+1. **Atomic Commits**: Each commit should be a logical unit
+2. **Commit Messages**: Focus on "why" not just "what"
+3. **Generated Code**: Include generated files in the same commit as source changes
+4. **Format**: Follow existing commit message style (see `git log --oneline -20`)
+
+## When Working on Features
+
+1. **Read Component Docs**: Check `docs/sources/reference-pyroscope-architecture/components/` for the component you're modifying
+2. **Understand the Ring**: If working on write/read path, understand consistent hashing
+3. **Multi-tenancy First**: Always consider multi-tenant implications
+4. **Check for Similar Code**: Pyroscope is inspired by Cortex/Mimir - similar patterns apply
+5. **Test Multi-tenancy**: Test with multiple tenants to catch isolation issues
+6. **Profile Your Changes**: Use `go test -bench` and verify performance impact
+7. **Update Documentation**: If changing user-facing behavior, update docs
+
+## Documentation Locations
+
+- **User Docs**: `docs/sources/` - Published to grafana.com
+- **Contributing**: `docs/internal/contributing/README.md`
+- **Component Docs**: `docs/sources/reference-pyroscope-architecture/components/`
+
+## Getting Help
+
+- **Contributing Guide**: `docs/internal/contributing/README.md`
+- **Code Comments**: The codebase has extensive comments - read them
+- **Git History**: Use `git blame` and `git log` to understand design decisions

.cursor/rules/go-backend.mdc

@@ -0,0 +1,154 @@
+---
+description: Go backend coding standards and patterns for Pyroscope
+globs:
+  - "**/*.go"
+  - "!**/*_test.go"
+---
+
+# Go Backend Development
+
+## Import Organization
+
+Always organize imports into three groups separated by blank lines:
+
+```go
+import (
+    // Standard library
+    "context"
+    "fmt"
+
+    // Third-party packages
+    "github.com/prometheus/client_golang/prometheus"
+    "go.uber.org/atomic"
+
+    // Internal packages
+    "github.com/grafana/pyroscope/pkg/model"
+    "github.com/grafana/pyroscope/pkg/objstore"
+)
+```
+
+**Don't** add imports within the three import groups (keep them separate).
+
+## Formatting & Linting
+
+- Use `golangci-lint` (run via `make lint`)
+- gofmt for formatting
+- goimports with `-local github.com/grafana/pyroscope`
+- Enabled linters: depguard, goconst, misspell, revive, unconvert, unparam
+
+## Logging
+
+- **Use**: `github.com/go-kit/log`
+- **Don't**: `github.com/go-kit/kit/log` (deprecated import path)
+- **Don't**: `fmt.Println` for logging
+
+Use structured logging:
+
+```go
+import "github.com/go-kit/log/level"
+
+level.Error(logger).Log("msg", "failed to process", "err", err)
+level.Info(logger).Log("msg", "processing complete", "count", count)
+```
+
+## Error Handling
+
+- Always check errors explicitly
+- Wrap errors with context:
+
+```go
+if err != nil {
+    return fmt.Errorf("failed to query: %w", err)
+}
+```
+
+## Context Usage
+
+- Always pass `context.Context` as the first parameter
+- Respect context cancellation in loops and long operations:
+
+```go
+func process(ctx context.Context, items []Item) error {
+    for _, item := range items {
+        select {
+        case <-ctx.Done():
+            return ctx.Err()
+        default:
+        }
+        // process item
+    }
+    return nil
+}
+```
+
+## Multi-tenancy Pattern
+
+All requests must include a tenant ID. Extract from context:
+
+```go
+import "github.com/grafana/pyroscope/pkg/tenant"
+
+tenantID, err := tenant.ExtractTenantIDFromContext(ctx)
+if err != nil {
+    return err
+}
+```
+
+**Never** hardcode tenant IDs.
+
+## Object Storage Pattern
+
+Use the abstract Bucket interface:
+
+```go
+import "github.com/grafana/pyroscope/pkg/objstore"
+
+bucket := objstore.NewBucket(cfg)
+reader, err := bucket.Get(ctx, "path/to/object")
+```
+
+## Configuration Pattern
+
+Use `github.com/grafana/dskit` for configuration:
+
+```go
+type Config struct {
+    ListenPort int `yaml:"listen_port"`
+}
+
+func (cfg *Config) RegisterFlags(f *flag.FlagSet) {
+    f.IntVar(&cfg.ListenPort, "server.http-listen-port", 4040, "HTTP listen port")
+}
+```
+
+## Performance Considerations
+
+1. **Minimize Allocations in Hot Paths**:
+   - Reuse buffers with `sync.Pool`
+   - Avoid string concatenation in loops
+   - Use `strings.Builder` for string building
+
+2. **Concurrency**:
+   - Use worker pools for bounded concurrency
+   - Prefer channels for coordination over mutexes when possible
+   - Don't create unbounded goroutines - use worker pools or semaphores
+
+3. **Profile Your Changes**:
+   ```bash
+   go test -cpuprofile=cpu.prof -memprofile=mem.prof -bench=.
+   go tool pprof cpu.prof
+   ```
+
+## Code Generation
+
+**IMPORTANT**: After changing protobuf, configs, or flags:
+```bash
+make generate
+```
+Commit the generated files with your changes.
+
+## Security
+
+1. **Input Validation**: Always validate and sanitize user input
+2. **Path Traversal**: Validate object keys before storage operations
+3. **Rate Limiting**: Distributor implements per-tenant rate limiting

.cursor/rules/go-testing.mdc

@@ -0,0 +1,140 @@
+---
+description: Go testing standards and patterns for Pyroscope
+globs:
+  - "**/*_test.go"
+---
+
+# Go Testing Standards
+
+## Test File Naming
+
+- Test files: `*_test.go`
+- Test function naming: `TestFunctionName` or `TestComponentName_Method`
+
+## Test Structure
+
+Use table-driven tests for multiple cases:
+
+```go
+func TestDistributor_Push(t *testing.T) {
+    t.Parallel()
+
+    tests := []struct {
+        name    string
+        input   *pushv1.PushRequest
+        wantErr bool
+    }{
+        {name: "valid request", input: validRequest(), wantErr: false},
+        {name: "invalid tenant", input: invalidRequest(), wantErr: true},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            d := setupDistributor(t)
+            err := d.Push(context.Background(), tt.input)
+            if tt.wantErr {
+                require.Error(t, err)
+            } else {
+                require.NoError(t, err)
+            }
+        })
+    }
+}
+```
+
+## Assertions
+
+- Use `require` for fatal assertions (test stops on failure)
+- Use `assert` for non-fatal assertions (test continues)
+
+```go
+import (
+    "github.com/stretchr/testify/assert"
+    "github.com/stretchr/testify/require"
+)
+
+// Fatal - stops test immediately
+require.NoError(t, err)
+require.NotNil(t, result)
+
+// Non-fatal - continues test
+assert.Equal(t, expected, actual)
+```
+
+## Test Organization
+
+1. **Subtests**: Use `t.Run()` for grouping related cases
+2. **Parallel Tests**: Use `t.Parallel()` when tests are independent
+3. **Cleanup**: Always use `t.Cleanup()` for resource cleanup
+
+```go
+func TestComponent(t *testing.T) {
+    t.Parallel()
+
+    resource := createResource(t)
+    t.Cleanup(func() {
+        resource.Close()
+    })
+
+    t.Run("subtest", func(t *testing.T) {
+        // test logic
+    })
+}
+```
+
+## Test Data
+
+- Store test data in `testdata/` directories
+- Use relative paths from the test file
+
+## Integration Tests
+
+Use build tags for integration tests:
+
+```go
+//go:build integration
+
+package mypackage_test
+
+func TestIntegration(t *testing.T) {
+    // ...
+}
+```
+
+## Mocking
+
+- Use `mockery` for generating mocks from interfaces
+- Place mocks in appropriate locations based on scope
+
+## Multi-tenancy Testing
+
+**Always test with multiple tenants** to catch isolation issues:
+
+```go
+func TestMultiTenant(t *testing.T) {
+    tenants := []string{"tenant-a", "tenant-b"}
+
+    for _, tenant := range tenants {
+        t.Run(tenant, func(t *testing.T) {
+            ctx := tenant.InjectTenantID(context.Background(), tenant)
+            // verify tenant isolation
+        })
+    }
+}
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+make go/test
+
+# Run specific package tests
+go test ./pkg/distributor/...
+
+# Run with race detector
+go test -race ./...
+
+# Run benchmarks
+go test -bench=. ./pkg/...
+```