DEV Community: Jhon Thomas Ticona Chambi

Observability Practices: A Complete Guide with Node.js Implementation

Jhon Thomas Ticona Chambi — Sat, 05 Jul 2025 04:33:47 +0000

Introduction

In today's distributed systems landscape, observability has become critical for understanding complex applications. This article demonstrates comprehensive observability practices using a real-world Node.js API integrated with Prometheus and Grafana.

The Three Pillars of Observability

1. Metrics

Numerical measurements providing quantitative insights:

Business Metrics: User registrations, transactions, revenue
Application Metrics: Response times, error rates, throughput
Infrastructure Metrics: CPU usage, memory consumption, disk I/O

2. Logs

Time-stamped records of discrete events:

Structured Logging: JSON format for better parsing
Contextual Information: Request IDs, user context, transaction details
Different Log Levels: DEBUG, INFO, WARN, ERROR, FATAL

3. Traces

Track requests across multiple services:

Distributed Tracing: Follow requests through microservices
Performance Analysis: Identify slow components
Dependency Mapping: Understand service relationships

Real-World Implementation with Node.js

Our demonstration project implements a RESTful API with comprehensive observability features.

Architecture Overview

Node.js API (Port 3000) → Prometheus (Port 9090) → Grafana (Port 3000)
                ↓
    Traffic Generator (Test Script)

Core Metrics Implementation

HTTP Request Duration Histogram

const httpDuration = new promClient.Histogram({
  name: 'http_request_duration_ms',
  help: 'Duration of HTTP requests in ms',
  labelNames: ['method', 'route', 'status'],
  buckets: [1, 5, 15, 50, 100, 500, 1000]
});

Request Counter

const httpRequests = new promClient.Counter({
  name: 'http_requests_total',
  help: 'Total HTTP requests',
  labelNames: ['method', 'route', 'status']
});

Active Connections Gauge

const activeConnections = new promClient.Gauge({
  name: 'active_connections',
  help: 'Active connections'
});

API Endpoints for Testing

GET / - Basic health endpoint
GET /users - List users with variable latency
GET /users/:id - Specific user lookup with error cases
GET /slow - Intentionally slow endpoint (2-5s response time)
GET /error - Random error generation for testing
GET /metrics - Prometheus metrics endpoint

Middleware Implementation

// Response time tracking
app.use(responseTime((req, res, time) => {
  const route = req.route ? req.route.path : req.path;

  httpDuration.labels(req.method, route, res.statusCode).observe(time);
  httpRequests.labels(req.method, route, res.statusCode).inc();

  if (res.statusCode >= 400) {
    httpErrors.labels(req.method, route, res.statusCode).inc();
  }
}));

Essential Prometheus Queries

Request Rate (RPS)

rate(http_requests_total[1m])

Error Rate Percentage

rate(http_errors_total[1m]) / rate(http_requests_total[1m]) * 100

95th Percentile Response Time

histogram_quantile(0.95, rate(http_request_duration_ms_bucket[1m]))

Best Practices

1. Metric Design Principles

Use Standard Suffixes: _total, _duration_seconds, _bytes
Consistent Labeling: Standardize label names across services
Avoid High Cardinality: Limit unique label combinations

2. Golden Signals Implementation

Latency: Time to process requests
Traffic: Demand on your system
Errors: Rate of failed requests
Saturation: Resource utilization

3. Effective Alerting

Alert on Symptoms: Focus on user impact, not causes
Meaningful Thresholds: Avoid alert fatigue
Runbook Integration: Provide clear remediation steps

GitHub Repository

The complete implementation with automated setup scripts is available:

🔗 GitHub Repository: https://github.com/jhonticonachambi/observability-practices-nodejs.git

Repository Features

✅ Complete source code with all implementation files
✅ Automated setup scripts for Windows/Mac/Linux
✅ Comprehensive documentation and troubleshooting guides
✅ CI/CD ready with GitHub Actions integration
✅ Traffic generator for realistic testing scenarios

Conclusion

Observability transforms raw metrics into actionable insights that drive better system reliability and user experience. This implementation demonstrates:

Holistic Approach: Combining metrics, logs, and traces
Practical Implementation: Real-world Node.js example
Automation First: Scripted setup reduces barriers
Best Practices: Following established patterns

Next Steps

Extend metrics with business-specific measurements
Implement meaningful alerting
Add distributed tracing with Jaeger
Apply patterns to production systems

Author: Jhon TiCona Chambi

Technologies: Node.js, Prometheus, Grafana, Express.js

Repository: https://github.com/jhonticonachambi/observability-practices-nodejs.git

Observability Practices: A Complete Guide with Node.js Implementation

Jhon Thomas Ticona Chambi — Sat, 05 Jul 2025 04:23:36 +0000

Introduction

The Three Pillars of Observability

1. Metrics

Numerical measurements providing quantitative insights:

Business Metrics: User registrations, transactions, revenue
Application Metrics: Response times, error rates, throughput
Infrastructure Metrics: CPU usage, memory consumption, disk I/O

2. Logs

Time-stamped records of discrete events:

Structured Logging: JSON format for better parsing
Contextual Information: Request IDs, user context, transaction details
Different Log Levels: DEBUG, INFO, WARN, ERROR, FATAL

3. Traces

Track requests across multiple services:

Distributed Tracing: Follow requests through microservices
Performance Analysis: Identify slow components
Dependency Mapping: Understand service relationships

Real-World Implementation with Node.js

Our demonstration project implements a RESTful API with comprehensive observability features.

Architecture Overview

Node.js API (Port 3000) → Prometheus (Port 9090) → Grafana (Port 3000)
                ↓
    Traffic Generator (Test Script)

Core Metrics Implementation

HTTP Request Duration Histogram

const httpDuration = new promClient.Histogram({
  name: 'http_request_duration_ms',
  help: 'Duration of HTTP requests in ms',
  labelNames: ['method', 'route', 'status'],
  buckets: [1, 5, 15, 50, 100, 500, 1000]
});

Request Counter

const httpRequests = new promClient.Counter({
  name: 'http_requests_total',
  help: 'Total HTTP requests',
  labelNames: ['method', 'route', 'status']
});

Active Connections Gauge

const activeConnections = new promClient.Gauge({
  name: 'active_connections',
  help: 'Active connections'
});

API Endpoints for Testing

GET / - Basic health endpoint
GET /users - List users with variable latency
GET /users/:id - Specific user lookup with error cases
GET /slow - Intentionally slow endpoint (2-5s response time)
GET /error - Random error generation for testing
GET /metrics - Prometheus metrics endpoint

Middleware Implementation

// Response time tracking
app.use(responseTime((req, res, time) => {
  const route = req.route ? req.route.path : req.path;

  httpDuration.labels(req.method, route, res.statusCode).observe(time);
  httpRequests.labels(req.method, route, res.statusCode).inc();

  if (res.statusCode >= 400) {
    httpErrors.labels(req.method, route, res.statusCode).inc();
  }
}));

Essential Prometheus Queries

Request Rate (RPS)

rate(http_requests_total[1m])

Error Rate Percentage

rate(http_errors_total[1m]) / rate(http_requests_total[1m]) * 100

95th Percentile Response Time

histogram_quantile(0.95, rate(http_request_duration_ms_bucket[1m]))

Best Practices

1. Metric Design Principles

Use Standard Suffixes: _total, _duration_seconds, _bytes
Consistent Labeling: Standardize label names across services
Avoid High Cardinality: Limit unique label combinations

2. Golden Signals Implementation

Latency: Time to process requests
Traffic: Demand on your system
Errors: Rate of failed requests
Saturation: Resource utilization

3. Effective Alerting

Alert on Symptoms: Focus on user impact, not causes
Meaningful Thresholds: Avoid alert fatigue
Runbook Integration: Provide clear remediation steps

GitHub Repository

The complete implementation with automated setup scripts is available:

🔗 GitHub Repository: https://github.com/jhonticonachambi/observability-practices-nodejs.git

Repository Features

✅ Complete source code with all implementation files
✅ Automated setup scripts for Windows/Mac/Linux
✅ Comprehensive documentation and troubleshooting guides
✅ CI/CD ready with GitHub Actions integration
✅ Traffic generator for realistic testing scenarios

Conclusion

Observability transforms raw metrics into actionable insights that drive better system reliability and user experience. This implementation demonstrates:

Holistic Approach: Combining metrics, logs, and traces
Practical Implementation: Real-world Node.js example
Automation First: Scripted setup reduces barriers
Best Practices: Following established patterns

Next Steps

Extend metrics with business-specific measurements
Implement meaningful alerting
Add distributed tracing with Jaeger
Apply patterns to production systems

Author: Jhon TiCona Chambi

Technologies: Node.js, Prometheus, Grafana, Express.js

Repository: https://github.com/jhonticonachambi/observability-practices-nodejs.git

Software Design Principles: Practical Implementation with User Roles

Jhon Thomas Ticona Chambi — Fri, 28 Mar 2025 22:38:27 +0000

I. Introduction

Software design is a fundamental pillar for developing scalable, maintainable, and flexible applications. To achieve this, we use the SOLID principles, a set of best practices in object-oriented programming.

In this document, we focus on two specific SOLID principles:

Liskov Substitution Principle (LSP)
Interface Segregation Principle (ISP)

Through a practical implementation based on user roles, we will see how these principles improve the structure and maintainability of the code.

II. SOLID Principles

The SOLID acronym represents five key principles in object-oriented programming:

S - Single Responsibility Principle (SRP): A class should have a single responsibility.
O - Open/Closed Principle (OCP): Code should be open for extension but closed for modification.
L - Liskov Substitution Principle (LSP): Subclasses should be able to replace their base class without altering functionality.
I - Interface Segregation Principle (ISP): Interfaces should be specific rather than general.
D - Dependency Inversion Principle (DIP): High-level modules should not depend on low-level modules but on abstractions.

In this project, we apply LSP and ISP to design a well-structured user role system.

III. Implementing LSP and ISP in a User Role System

In a system where users have different roles (Reader, Editor, Administrator), applying LSP and ISP is key to ensuring flexibility and maintainability.

A. Applying Liskov Substitution Principle (LSP)

The Liskov Substitution Principle states that a subclass should be able to replace its base class without affecting expected behavior.

How we apply it in our implementation:

We create a base class User with common attributes (name and email).
The Reader, Editor, and Admin classes inherit from User, making them interchangeable in the code.
Each subclass implements only the necessary functionalities without modifying base behavior.

This ensures that we can substitute a User with any subclass (Reader, Editor, Admin) without affecting the overall functionality of the system.

B. Applying Interface Segregation Principle (ISP)

The Interface Segregation Principle states that it's preferable to have several specific interfaces rather than a single general one with many responsibilities.

How we apply it in our implementation:

Instead of a single general interface for all users, we create separate interfaces:
- IReader: For users with reading permissions.
- IEditor: For users with editing permissions.
- IAdmin: For users with administrative permissions.
Each class implements only the interfaces it needs, avoiding unnecessary methods.

This reduces unnecessary dependencies and improves system scalability.

IV. Implementation Code

from abc import ABC, abstractmethod

# Specific Interfaces (ISP)
class IUser(ABC):
    @abstractmethod
    def get_name(self) -> str: pass

class IReader(ABC):
    @abstractmethod
    def read_content(self) -> str: pass

class IEditor(ABC):
    @abstractmethod
    def edit_content(self) -> str: pass

class IAdmin(ABC):
    @abstractmethod
    def delete_content(self) -> str: pass

# Base Class (LSP)
class User(IUser):
    def __init__(self, name): self.name = name
    def get_name(self) -> str: return self.name

# Subclasses applying LSP and ISP
class Reader(User, IReader):
    def read_content(self) -> str: return f"{self.name} is reading."

class Editor(Reader, IEditor):
    def edit_content(self) -> str: return f"{self.name} has edited content."

class Admin(Editor, IAdmin):
    def delete_content(self) -> str: return f"{self.name} has deleted content."

V. Conclusion

By applying Liskov Substitution Principle (LSP) and Interface Segregation Principle (ISP), we have built a more flexible, scalable, and maintainable user role system.

LSP ensures that subclasses can replace their base class without altering the system’s expected behavior.
ISP ensures that classes implement only the necessary interfaces, avoiding bloated and unnecessary dependencies.

These principles contribute to clean code, facilitating future modifications and reducing complexity in large-scale applications.

For more details and source code, visit the GitHub repository: SOLID User Roles.