shared-logging 0.1.0

# Installation Guide

This guide explains the different ways to install and use `shared-logging` in your projects.

## Quick Reference

| Method | Use Case | Example |
|--------|----------|---------|
| **Path dependency** | Local development | `path = "../shared-logging"` |
| **Git dependency** | From repository | `git = "https://github.com/..."` |
| **Crates.io** | Published version | `version = "0.1.0"` |
| **Workspace** | Multiple projects | Workspace setup |

## Method 1: Local Path Dependency

**Best for:** Local development, testing changes, developing alongside your app

### Setup

If your project structure looks like this:
```
projects/
├── shared-logging/     # The logging library
└── my-service/         # Your application
```

Add to `my-service/Cargo.toml`:
```toml
[dependencies]
shared-logging = { path = "../shared-logging" }
```

### With Features

```toml
[dependencies]
shared-logging = { 
    path = "../shared-logging",
    features = ["http"]  # Enable HTTP middleware
}

# Or multiple features
shared-logging = { 
    path = "../shared-logging",
    features = ["http", "otel"]  # Enable both HTTP and OpenTelemetry
}
```

### Advantages
- ✅ Instant feedback when making changes
- ✅ No need to publish or push changes
- ✅ Easy to debug and develop

### Disadvantages
- ❌ Path must be correct relative to your project
- ❌ Not suitable for production deployments (unless using workspaces)

## Method 2: Git Dependency

**Best for:** Using a specific version from a Git repository

### Setup

```toml
[dependencies]
shared-logging = { git = "https://github.com/kelleyblackmore/shared-logging" }
```

### Specific Branch or Tag

```toml
# Use a specific branch
shared-logging = { 
    git = "https://github.com/kelleyblackmore/shared-logging",
    branch = "main"
}

# Use a specific tag/version
shared-logging = { 
    git = "https://github.com/kelleyblackmore/shared-logging",
    tag = "v0.1.0"
}

# Use a specific commit
shared-logging = { 
    git = "https://github.com/kelleyblackmore/shared-logging",
    rev = "abc123def456"
}
```

### With Features

```toml
shared-logging = { 
    git = "https://github.com/kelleyblackmore/shared-logging",
    features = ["http"]
}
```

### Advantages
- ✅ Version control via Git
- ✅ Can pin to specific commits/tags
- ✅ Works across different machines

### Disadvantages
- ❌ Requires internet access to fetch
- ❌ Slower than local path

## Method 3: Published to crates.io

**Best for:** Production use, version management, public distribution

### Setup

Once published, use it like any other crate:

```toml
[dependencies]
shared-logging = "0.1.0"
```

### Version Constraints

```toml
# Exact version
shared-logging = "0.1.0"

# Compatible versions (semver)
shared-logging = "~0.1.0"  # >=0.1.0, <0.2.0
shared-logging = "^0.1.0"  # >=0.1.0, <0.2.0 (default)
shared-logging = ">=0.1.0, <0.2.0"

# Latest version
shared-logging = "*"  # Not recommended for production
```

### With Features

```toml
shared-logging = { version = "0.1.0", features = ["http", "otel"] }
```

### Publishing (For Maintainers)

To publish to crates.io:

```bash
# 1. Create an account on crates.io
# 2. Get your API token
# 3. Login
cargo login YOUR_API_TOKEN

# 4. Publish
cargo publish
```

### Advantages
- ✅ Standard Rust ecosystem approach
- ✅ Version management via semver
- ✅ Easy for others to use
- ✅ Cargo handles caching

### Disadvantages
- ❌ Requires publishing process
- ❌ Changes require new version

## Method 4: Cargo Workspace

**Best for:** Managing multiple projects that share the logging library

### Setup

Create a workspace structure:

```
my-workspace/
├── Cargo.toml          # Workspace root
├── shared-logging/      # The logging library
│   └── Cargo.toml
├── service-a/           # Your first service
│   └── Cargo.toml
└── service-b/           # Your second service
    └── Cargo.toml
```

**Workspace root `Cargo.toml`:**
```toml
[workspace]
members = [
    "shared-logging",
    "service-a",
    "service-b",
]

[workspace.package]
version = "0.1.0"
edition = "2021"
```

**Service `Cargo.toml` (e.g., `service-a/Cargo.toml`):**
```toml
[package]
name = "service-a"
version.workspace = true
edition.workspace = true

[dependencies]
shared-logging = { path = "../shared-logging" }
```

### Advantages
- ✅ Single `cargo build` for all projects
- ✅ Shared dependencies
- ✅ Coordinated versioning
- ✅ Easy refactoring across projects

### Disadvantages
- ❌ Requires workspace structure
- ❌ All projects must be in same directory tree

## Feature Flags

The crate supports optional features:

- **`http`**: HTTP middleware support (tower-http)
- **`otel`**: OpenTelemetry integration

### Enabling Features

```toml
# Single feature
shared-logging = { path = "../shared-logging", features = ["http"] }

# Multiple features
shared-logging = { path = "../shared-logging", features = ["http", "otel"] }

# Default features (if any)
shared-logging = { path = "../shared-logging", default-features = false }
```

## Verification

After adding the dependency, verify it works:

```bash
# Check that it compiles
cargo check

# Or run your project
cargo run
```

## Troubleshooting

### "Could not find `shared-logging`"

- Check the path is correct relative to your project
- Verify the `shared-logging` directory exists
- Ensure `Cargo.toml` in `shared-logging` has the correct `[package]` name

### "Package `shared-logging` not found in registry"

- If using Git, check the URL is correct
- If using crates.io, ensure the version exists
- Try `cargo update` to refresh the registry

### Feature not available

- Ensure you've enabled the feature in `Cargo.toml`
- Check that the feature exists in the crate's `Cargo.toml`
- Verify you're using a version that supports the feature

## Recommended Setup for Development

For local development, we recommend:

1. **Use path dependencies** during development
2. **Use Git dependencies** for staging/testing
3. **Use crates.io** for production

Example development setup:
```toml
[dependencies]
# Local development
shared-logging = { path = "../shared-logging" }

# Or for production-ready code
# shared-logging = { git = "https://github.com/kelleyblackmore/shared-logging", tag = "v0.1.0" }
```