📚 Appendix

Glossary

Term	Definition
Trace Flag	Salesforce setting enabling debug logging for a user or class over a period. Created via Tooling API.
Trace Job	Managed trace job in Apexium that auto-renews trace flags using a sliding window before the 24-hour expiry.
Debug Log	Generated log file with debug statements and system events. Stored in Salesforce for 24h, in Apexium for 15+ days.
Debug Level	Configuration controlling which events are logged (e.g., DB, FINEST, PROFILING).
Apex Class	Compiled Apex code unit in Salesforce. Tracked by Apexium for metadata changes.
Apex Trigger	Apex code that runs before/after DML events. Tracked by Apexium for metadata changes.
Coverage	Percentage of Apex code executed by tests. Viewed via Apexium's coverage reports.
Metadata	Apex classes, triggers, reports, debug levels, and other Salesforce configuration objects.
Connected App	Salesforce app configured with OAuth 2.0 (Client Credentials flow) for API access.
MinIO	S3-compatible object storage used by Apexium for log bodies and metadata snapshots.
Org Context	Multi-org management — Apexium tracks which Salesforce org is currently active.

Troubleshooting

Authentication

Error	Cause	Fix
INVALID_SESSION_ID	Token expired or invalid	Run ./apexium init to re-authenticate
unauthorized_url	Wrong instance URL	Check SALESFORCE_INSTANCE_ORG in .env
invalid_client	Bad credentials	Verify Consumer Key/Secret in Connected App

Logs

Issue	Cause	Fix
No logs appearing	No trace flag active	Create a trace job: POST /api/sfdc/logs/trace-jobs
Logs not storing	MinIO not running	Check docker compose ps, restart if needed
Old logs missing	Retention cleanup ran	Default is 15 days, adjust log.retention.days

Metadata

Issue	Cause	Fix
Changes not detected	Polling interval	Metadata polls every 6 hours, wait or restart
No classes showing	Not synced yet	Wait for next metadata poll cycle
Diff not available	No history recorded	Changes only tracked after Apexium starts polling

Infrastructure

Issue	Cause	Fix
Backend won't start	Port 8080 in use	Stop conflicting service or change port
PostgreSQL connection refused	DB not healthy	docker compose restart db, check logs
Redis connection refused	Redis not running	docker compose restart redis
MinIO bucket missing	First run	Bucket created automatically on startup

FAQ

General

Q: Can I use it without the web UI? A: Yes. The backend REST API is fully functional. Use curl or any HTTP client.

Q: How long are logs stored? A: 15 days by default. Configurable via log.retention.days in .env.

Q: Is it free? A: Yes. MIT licensed open source.

Q: Which Salesforce editions are supported? A: Any edition with API access (Developer, Enterprise, Unlimited). Professional Edition requires API add-on.

Trace Flags

Q: What happens when a trace flag expires? A: If managed by a Trace Job, it auto-renews before expiry. Manual flags expire and stop logging.

Q: Can I trace multiple users at once? A: Yes. Create separate trace jobs for each user.

Q: How long can I keep a trace flag active? A: Indefinitely with Trace Jobs — they use a sliding window to renew before the 24-hour limit.

Metadata

Q: How often does Apexium check for changes? A: Every 6 hours by default. Configurable via metadata.poll.rate.

Q: Does it track all metadata types? A: Currently tracks Apex Classes, Apex Triggers, and Reports. More types planned.

Deployment

Q: Can I run without Docker? A: Yes. Run PostgreSQL, Redis, and MinIO separately, then ./mvnw spring-boot:run.

Q: What's the minimum Java version? A: Java 21+. The Dockerfile uses Eclipse Temurin 25.

Q: Can I use an existing PostgreSQL instance? A: Yes. Set DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD in .env.

Useful Endpoints

Quick reference for common operations:

# Health check
curl http://localhost:8080/actuator/health

# List logs from database
curl http://localhost:8080/api/sfdc/logs/db

# Create a trace job
curl -X POST http://localhost:8080/api/sfdc/logs/trace-jobs \
  -H "Content-Type: application/json" \
  -d '{"userId":"005...","startTime":"2026-09-15T09:00:00Z","endTime":"2026-09-15T17:00:00Z","logLevel":"DEBUG"}'

# Get metadata history
curl http://localhost:8080/api/sfdc/metadata/history/class/01p...

# Flush cache
curl -X POST http://localhost:8080/admin/cache/flush

# Swagger UI
open http://localhost:8080/swagger-ui.html

References

Resource	Link
GitHub Repository	github.com/ichwansh03/apexium-log
Docker Hub	hub.docker.com/r/ichwansh03/apexium-log-app
Salesforce Tooling API	developer.salesforce.com/docs/atlas.en-us.api_tooling.meta
Salesforce REST API	developer.salesforce.com/docs/atlas.en-us.api_rest.meta
Spring Boot Docs	spring.io/projects/spring-boot
MinIO Docs	min.io/docs