Frequently Asked Questions

Find answers to common questions about Logstyx, the open-source logging platform.

General Questions

What is Logstyx?

Logstyx is an open-source, self-hosted logging platform built on a microservices architecture. It provides a complete solution for collecting, storing, and viewing application logs with security features like encryption at rest with hashed indexing.

Why should I use Logstyx?

Logstyx is ideal if you need:

Complete data ownership: All your logs stay on your infrastructure
Privacy and security: Built-in encryption for sensitive data
Cost control: No per-GB pricing or surprise bills
Self-hosted solution: No vendor lock-in
Modern architecture: Microservices-based and scalable

How is Logstyx different from commercial logging platforms?

Feature	Logstyx	Commercial Platforms (Splunk, Datadog, Loggly)
Hosting	Self-hosted	Cloud-hosted (SaaS)
Cost	Free (infrastructure only)	~$0.10-$0.50 per GB + licensing
Data ownership	Complete control	Data stored on vendor servers
Privacy	encryption at rest	Varies by provider
Vendor lock-in	None	High
Search capabilities	Exact match only	Full-text and fuzzy search
Setup complexity	Medium (Docker required)	Low (SaaS)
Maintenance	Self-managed	Fully managed

Is Logstyx really free?

Yes, Logstyx is 100% open source and free to use. You only pay for your own infrastructure costs (servers, storage, bandwidth). There are no licensing fees, per-GB charges, or hidden costs.

What are the limitations compared to commercial solutions?

The main limitation is search capabilities:

✅ Logstyx: Exact match queries only (due to hashed indexing for privacy)
❌ Commercial platforms: Full-text search, fuzzy matching, advanced query languages

This trade-off prioritizes privacy and performance over search flexibility. If you need partial text search across all logs, consider commercial alternatives like Datadog, Splunk, or the ELK Stack.

Installation & Setup

What are the system requirements?

Minimum requirements:

Docker and Docker Compose installed
2 GB RAM
10 GB disk space
Linux, macOS, or Windows with WSL2

Recommended for production:

4+ GB RAM
50+ GB disk space (depending on log volume)
SSD storage for better performance

How do I install Logstyx?

The quickest way is using the one-line installer:

bash

curl -fsSL https://raw.githubusercontent.com/devatlogstyx/logstyx/main/install.sh | bash

This installer will:

Check Docker prerequisites
Collect your admin credentials
Generate encryption keys
Create configuration files
Optionally start services immediately

For manual installation, see the main repository.

Can I use external databases instead of bundled ones?

Yes! Logstyx supports external services via environment variables:

MongoDB: Set MONGODB_HOST
Redis: Set REDIS_URL
RabbitMQ: Set AMQP_HOST

This is useful if you already have these services running or want to use managed database services.

How do I configure SSL/HTTPS?

Logstyx doesn't include built-in SSL handling. For production, put it behind a reverse proxy like:

Nginx
Traefik
Caddy (auto-SSL with Let's Encrypt)

Example nginx configuration:

nginx

server {
    listen 443 ssl;
    server_name logs.yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Can I run Logstyx on Kubernetes?

While Logstyx is Docker-based and could theoretically run on Kubernetes, there are no official Kubernetes manifests or Helm charts yet. You would need to create these yourself.

For most use cases, Docker Compose is sufficient and easier to maintain.

Architecture & Technical

What is the architecture of Logstyx?

Logstyx uses a microservices architecture:

┌─────────────┐
│   Gateway   │  ← HTTP requests
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  RabbitMQ   │  ← Message queue
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    Core     │  ← Log processing & authorization
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   MongoDB   │  ← Encrypted storage
└─────────────┘

Services:

Gateway Service: Entry point for API requests
Authentication Service: User authentication and authorization
Core Service: Log processing and validation
Cache Service: Redis-based caching layer
Utility Service: Helper functions
Frontend: React-based dashboard

Why does Logstyx use hashed indexing?

Hashed indexing provides:

Privacy: Log identifiers are hashed, making it harder to correlate logs without proper authorization
Performance: Hash-based lookups are faster than full-text search
Security: Adds an extra layer of protection for sensitive data

The trade-off is that you can only search for exact matches, not partial text.

How are logs encrypted?

Logstyx uses multiple layers of encryption:

At rest: Sensitive log data is encrypted in MongoDB
In transit: Use HTTPS (via reverse proxy) for encrypted transmission
Configuration: Environment variables can be encrypted with the ENC_ prefix
Secrets: Encryption keys are generated during installation

Why use RabbitMQ?

RabbitMQ provides:

Reliability: Messages are persisted to disk
Asynchronous processing: API returns immediately while logs are processed in background
Scalability: Easy to scale consumers independently
Resilience: Logs won't be lost even if processing fails temporarily

Can I scale Logstyx horizontally?

Yes! Each microservice can be scaled independently:

yaml

# docker-compose.yml
services:
  core-service:
    deploy:
      replicas: 3  # Run 3 instances

You can also:

Add more RabbitMQ consumers for faster processing
Use MongoDB replica sets for database redundancy
Use Redis Cluster for distributed caching

Usage & Integration

Which SDKs are available?

Official SDKs:

logstyx-js-core - Core JavaScript SDK
logstyx-js-react - React integration
logstyx-js-react-native - React Native
logstyx-js-node - Node.js
logstyx-js-browser - Browser
logstyx-js-express - Express.js

Can I use Logstyx without the SDKs?

Yes! You can send logs directly to the API endpoint POST /api/v1/logs. This is useful for:

Building SDKs for other languages (Python, Go, Java, etc.)
Custom integrations
Systems that can't use JavaScript

See the API Endpoints documentation for details.

How do I authenticate API requests?

Logstyx supports three authentication methods depending on your client type:

Browser clients: Origin validation (whitelist domains in project settings)
Mobile clients: App ID validation (configure in project settings)
Server clients: HMAC-SHA256 signature (using project secret)

See Authentication documentation for implementation details.

What log levels are supported?

If you use the SDKm it provide four default log levels:

Level	Use Case
`info`	General application events, user actions
`warning`	Potential issues that don't stop execution
`error`	Runtime errors, failed operations
`critical`	System failures, security breaches

But you can always send a custom log level.

Can I send logs in batches?

The API doesn't support batch endpoints, but you can implement client-side batching to reduce network requests. See the batching example in the API documentation.

How do I handle rate limits?

The API is rate-limited to 20 requests per second per IP with a burst allowance of 50 requests.

Best practices:

Implement client-side batching
Add exponential backoff for retries
Use queuing on high-volume clients
Monitor your request rates

Data & Privacy

How long are logs retained?

Log retention is configured in your Logstyx instance. By default, logs are kept for 1 hour. You can implement custom retention policies updating retentionHours on Project setting:

Can I export my logs?

Yes, your logs are stored in MongoDB. You can export them manually mongoexport but everything is still encrypted.

What data is logged by default?

Logstyx only stores what you send via the API:

Log level
Project ID
Timestamp
Device identifier (optional)
Context object (optional)
Data object (your actual log content)

Logstyx does not automatically collect:

IP addresses (unless you include them)
User agents
Geographic location
Personal information

Logstyx itself doesn't collect personal data. However, you are responsible for ensuring your logging practices comply with GDPR:

✅ Do:

Implement data retention policies
Anonymize or hash personal identifiers
Provide mechanisms for data deletion
Document what you log

❌ Don't:

Log passwords or authentication tokens
Log personal identification numbers
Log credit card information
Log data without user consent (where required)

Since you control the infrastructure, you have full control over compliance.

Can I delete logs?

Yes, you can delete logs through:

Dashboard: Deleting Project will drop all logs in the UI
Direct database access: Use MongoDB commands

Performance & Scalability

How many logs can Logstyx handle?

Performance depends on your hardware, but typical numbers:

Small deployment (2 GB RAM): ~1,000 logs/second
Medium deployment (8 GB RAM): ~10,000 logs/second
Large deployment (16+ GB RAM, scaled services): 50,000+ logs/second

Bottlenecks are usually:

MongoDB write performance (use SSDs)
RabbitMQ throughput (scale consumers)
Network bandwidth

How much storage do logs consume?

Storage varies based on log content, but averages:

Simple log (50 bytes): ~50 bytes
Typical log (500 bytes): ~500 bytes
Detailed log (2 KB): ~2 KB

Example: 1 million logs/day at 500 bytes each = ~500 MB/day = ~15 GB/month

MongoDB compression can reduce this by 60-80%.

What happens when storage is full?

MongoDB will stop accepting writes when storage is full. Monitor disk space and implement:

Automatic cleanup: Delete old logs periodically
Alerts: Monitor disk usage and get notified
Archiving: Move old logs to cheaper storage

Can I use cloud storage for logs?

Yes, you can:

Run Logstyx on cloud VMs: AWS EC2, Google Cloud, Azure, DigitalOcean
Use managed databases:
- MongoDB Atlas
- Amazon ElastiCache (Redis)
- Amazon MQ (RabbitMQ)

Troubleshooting

Logs aren't appearing in the dashboard

Common causes:

Authentication failure: Check your project ID, origin, app ID, or signature
Invalid format: Ensure required fields are present (level, projectId, data)
Rate limiting: Check if you're exceeding 20 requests/second
Processing delay: Wait a few seconds for asynchronous processing

Debug steps:

Check Docker logs: docker compose logs -f core-service
Verify RabbitMQ queue: Visit http://localhost:15672 (guest/guest)
Check MongoDB: Query the database directly
Test with a simple curl request

Services won't start

Common issues:

Port conflicts: Another service is using ports 5000, 5672, 27017, or 6379
Insufficient memory: Docker needs at least 2 GB RAM
Missing .env file: Run the installer or create .env.encrypted manually
Docker not running: Ensure Docker daemon is running

Solution:

bash

# Check Docker status
docker info

# Check port conflicts
sudo lsof -i :5000
sudo lsof -i :27017

# Restart all services
docker compose down
docker compose up -d

High memory usage

Causes:

MongoDB caching too much data
RabbitMQ message backlog
Too many concurrent log requests

Solutions:

yaml

# Limit MongoDB memory in docker-compose.yml
services:
  mongodb:
    command: mongod --wiredTigerCacheSizeGB 1

Implement log batching on clients to reduce request frequency.

Signature validation always fails

Checklist:

[ ] Field order: level, projectId, device, context, data
[ ] Signature is uppercase
[ ] Timestamp converted to integer
[ ] Using correct project secret
[ ] JSON has no extra spaces

See the signature debugging guide for detailed troubleshooting.

Comparison with Alternatives

Why not use OpenTelemetry?

OpenTelemetry (OTel) is a powerful observability standard, but it's designed for a different use case than Logstyx.

Key differences:

Aspect	Logstyx	OpenTelemetry
Primary goal	Developer-accessible logging	Complete observability (traces, metrics, logs)
Target user	Developers debugging their code	Platform/DevOps teams
Payload size	Minimal (~500 bytes typical)	Large (includes spans, traces, extensive metadata)
Authentication	Built-in (origin validation, HMAC signatures)	Not included in protocol
Workflow	`logger.info()` → see in dashboard	Instrument code → configure collector → query backend

Why Logstyx doesn't use OTel:

Different philosophy: Logstyx is designed to allow developers to safely and easily view logs from deployed applications without SSH access, cloud dashboard sharing, or SaaS lock-in, not to build a complete observability stack. You shouldn't need to understand spans, traces, or collectors just to see what your application is logging.
Payload overhead: OTel payloads include extensive metadata (resource attributes, instrumentation scope, trace context, etc.) that can be 5-10x larger than needed for simple logging. This increases bandwidth costs and storage requirements unnecessarily.
Authentication gap: The OTel protocol doesn't define authentication mechanisms. You need to layer this on separately, which adds complexity. Logstyx has authentication built into the API from day one.
Complexity barrier: OTel requires understanding collectors, exporters, receivers, and processors. Logstyx intentionally avoids this complexity—if you can call an API, you can send logs.
Use case mismatch: OTel excels at distributed tracing and correlated observability across microservices. Logstyx excels at letting developers quickly see application logs without infrastructure access.

When to use OTel instead:

You need distributed tracing across services
You're building a complete observability platform
You need to correlate logs, metrics, and traces
Your team already has OTel expertise

When to use Logstyx:

You just want developers to see logs without SSH
You want minimal setup and learning curve
You prefer lightweight payloads
You need built-in authentication and encryption

Think of it this way: OTel is a professional-grade observability framework. Logstyx is a developer-friendly log viewer. Different tools for different needs.

Can I use Logstyx alongside OpenTelemetry?

Yes, absolutely! Logstyx and OpenTelemetry serve complementary purposes and work well together.

Common setup:

javascript

// Use OTel for distributed tracing and metrics
import { trace } from '@opentelemetry/api';
const tracer = trace.getTracer('my-service');

// Use Logstyx for developer-accessible application logs
import { logger } from 'logstyx-js-node';

function processOrder(orderId) {
  const span = tracer.startSpan('process-order');
  
  // Logstyx: Simple logging for developers
  logger.info('Processing order', { orderId, timestamp: Date.now() });
  
  try {
    // ... business logic ...
    logger.info('Order processed successfully', { orderId });
  } catch (error) {
    // Logstyx: Quick error visibility
    logger.error('Order processing failed', { orderId, error: error.message });
    span.recordException(error);
  } finally {
    span.end();
  }
}

Benefits of using both:

OTel: Platform/SRE teams get traces, metrics, and service maps
Logstyx: Developers get instant log access without learning OTel query languages
Separation of concerns: Operations data vs. developer debugging data
Cost efficiency: Smaller Logstyx payloads for high-volume application logs, OTel for critical traces

When this makes sense:

Your ops team needs distributed tracing (OTel)
Your devs need quick log access (Logstyx)
You want to keep operational observability separate from developer debugging
You're avoiding giving all developers access to expensive OTel backends

Teams can run both: OTel for infrastructure and SRE teams, Logstyx for developers who just need to see what their code is doing.

Can I send OpenTelemetry payloads directly to Logstyx?

No. Even though Logstyx uses a /logs endpoint (similar to OTel), the payload formats are incompatible.

Why it doesn't work:

Different payload structure: OTel uses a complex nested format with resource attributes, instrumentation scopes, and log records. Logstyx expects a simple JSON structure with level, projectId, and data.
Authentication mismatch: Logstyx requires authentication (HMAC signatures, origin validation, or app ID). OTel payloads don't include this.
No OTel receiver: Logstyx doesn't implement an OTel collector/receiver, so it won't parse OTel protobuf or JSON formats.

Your options:

Use both separately (recommended):
- Send traces/metrics to your OTel backend
- Send application logs to Logstyx using the SDK
Build an adapter: Create a service that receives OTel logs and transforms them to Logstyx format before forwarding
Extract from OTel collector: Configure your OTel collector to forward logs to Logstyx via a custom exporter

Logstyx vs ELK Stack (Elasticsearch, Logstash, Kibana)

Feature	Logstyx	ELK Stack
Setup complexity	Low (one command)	High (manual configuration)
Resource usage	Light (2+ GB RAM)	Heavy (8+ GB RAM minimum)
Search capabilities	Exact match	Full-text search
Built-in security	Yes (encryption)	Requires X-Pack
Maintenance	Low	High
Scalability	Good	Excellent

Choose ELK if: You need powerful full-text search and have resources for maintenance.

Choose Logstyx if: You want quick setup, lower resource usage, and built-in encryption.

Logstyx vs Loki (Grafana)

Feature	Logstyx	Loki
Learning curve	Low	Medium
Storage efficiency	Good	Excellent
Querying	Simple	LogQL (powerful)
Integration	Standalone	Grafana ecosystem
Encryption	Built-in	Manual setup

Choose Loki if: You're already using Grafana and need log aggregation.

Choose Logstyx if: You want a complete standalone solution with encryption.

Logstyx vs Datadog/Splunk (Commercial)

Feature	Logstyx	Commercial SaaS
Cost	Free (infrastructure only)	$0.10-$0.50/GB + licenses
Data ownership	Complete	None (stored on their servers)
Privacy	Full control	Depends on vendor
Features	Basic logging	APM, metrics, traces, etc.
Maintenance	Self-managed	Fully managed
Support	Community	Enterprise support

Choose commercial if: You need full observability, managed service, and enterprise support.

Choose Logstyx if: You prioritize data ownership, privacy, and cost control.

Contributing & Community

How can I contribute?

Contributions are welcome! You can:

Report bugs via GitHub Issues
Submit pull requests with improvements
Create SDKs for other languages
Improve documentation
Share your use cases

Can I build my own SDK?

Absolutely! The API is documented and designed to be language-agnostic. If you build an SDK for Python, Go, Java, or another language, we'd love to hear about it!

See the API documentation for implementation details.

Where can I get help?

Documentation: Check these docs first
GitHub Discussions: Ask the community
GitHub Issues: Report bugs
Source code: The code is open for inspection

Future & Roadmap

What features are planned?

While specific roadmap items aren't public, we'd love to hear your take:

Can I request features?

Yes! Open a feature request on GitHub Issues with the enhancement label.

Is commercial support available?

Currently, Logstyx is community-supported through GitHub. For custom development or consulting, you can reach out to the maintainers directly.

Still have questions?

If your question isn't answered here:

Search GitHub Discussions
Ask in GitHub Discussions
Report bugs on GitHub Issues

We're here to help! 🚀

Frequently Asked Questions ​

General Questions ​

What is Logstyx? ​

Why should I use Logstyx? ​

How is Logstyx different from commercial logging platforms? ​

Is Logstyx really free? ​

What are the limitations compared to commercial solutions? ​

Installation & Setup ​

What are the system requirements? ​

How do I install Logstyx? ​

Can I use external databases instead of bundled ones? ​

How do I configure SSL/HTTPS? ​

Can I run Logstyx on Kubernetes? ​

Architecture & Technical ​

What is the architecture of Logstyx? ​

Why does Logstyx use hashed indexing? ​

How are logs encrypted? ​

Why use RabbitMQ? ​

Can I scale Logstyx horizontally? ​

Usage & Integration ​

Which SDKs are available? ​

Can I use Logstyx without the SDKs? ​

How do I authenticate API requests? ​

What log levels are supported? ​

Can I send logs in batches? ​

How do I handle rate limits? ​

Data & Privacy ​

How long are logs retained? ​

Can I export my logs? ​

What data is logged by default? ​

Is Logstyx GDPR compliant? ​

Can I delete logs? ​

Performance & Scalability ​

How many logs can Logstyx handle? ​

How much storage do logs consume? ​

What happens when storage is full? ​

Can I use cloud storage for logs? ​

Troubleshooting ​

Logs aren't appearing in the dashboard ​

Services won't start ​

High memory usage ​

Signature validation always fails ​

Comparison with Alternatives ​

Why not use OpenTelemetry? ​

Can I use Logstyx alongside OpenTelemetry? ​

Can I send OpenTelemetry payloads directly to Logstyx? ​

Logstyx vs ELK Stack (Elasticsearch, Logstash, Kibana) ​

Logstyx vs Loki (Grafana) ​

Logstyx vs Datadog/Splunk (Commercial) ​

Contributing & Community ​

How can I contribute? ​

Can I build my own SDK? ​

Where can I get help? ​

Future & Roadmap ​

What features are planned? ​

Can I request features? ​

Is commercial support available? ​

Still have questions? ​