Installation

Getting started with 9n9s is quick and straightforward. This guide covers everything you need to begin monitoring your systems and processes.

Account Setup

1. Create Your Account

Visit 9n9s.com/sign-up to create your free account:

1. Sign up with your email and password
2. Verify your email address via the confirmation link
3. Create your organization - this will be your team’s workspace
4. Set up your first project to organize your monitors

2. Account Security

We highly recommend enabling two-factor authentication (2FA) immediately:

1. Go to Settings > Security in your dashboard
2. Click Enable Two-Factor Authentication
3. Scan the QR code with your authenticator app (Google Authenticator, Authy, etc.)
4. Enter the verification code to confirm setup
5. Save your backup codes in a secure location

3. Organization Configuration

Configure your organization settings:

• Organization Name: Your team or company name
• Timezone: Default timezone for cron schedules
• Notification Preferences: Default channels for alerts
• Billing Information: Add payment method for paid features

SDK Installation

Install the 9n9s SDK for your preferred programming language to integrate heartbeat monitoring into your applications.

Python

# Install via pip
pip install 9n9s

# Or using poetry
poetry add 9n9s

# Or using pipenv
pipenv install 9n9s

Basic Usage:

from nines import Nines

# Initialize with your heartbeat monitor ID
nines = Nines("your-heartbeat-monitor-id")

# Signal successful completion
nines.pulse()

# Track execution time
@nines.time
def my_background_job():
    # Your job logic here
    process_data()

Node.js / TypeScript

# Install via npm
npm install @9n9s/sdk

# Or using yarn
yarn add @9n9s/sdk

# Or using pnpm
pnpm add @9n9s/sdk

Basic Usage:

import { Nines } from "@9n9s/sdk";

// Initialize with your heartbeat monitor ID
const nines = new Nines("your-heartbeat-monitor-id");

// Signal successful completion
await nines.pulse();

// Track execution time
await nines.time(async () => {
    // Your job logic here
    await processData();
});

Go

# Install the Go module
go get github.com/9n9s-io/9n9s-go

Basic Usage:

package main

import (
    "github.com/9n9s-io/9n9s-go"
)

func main() {
    // Initialize with your heartbeat monitor ID
    nines := nines.New("your-heartbeat-monitor-id")

    // Signal successful completion
    nines.Pulse()

    // Track execution time
    err := nines.Time(func() error {
        // Your job logic here
        return processData()
    })

    if err != nil {
        // Handle error
    }
}

Other Languages

SDKs for additional languages are in development:

• Java: Coming Q2 2024
• .NET/C#: Coming Q2 2024
• PHP: Coming Q3 2024
• Ruby: Coming Q3 2024
• Rust: Coming Q3 2024

For languages without official SDKs, you can use the HTTP API endpoints directly.

CLI Tool Installation

The 9n9s CLI tool provides command-line access to manage monitors, send pulses, and automate configuration.

Install via Package Managers

macOS (Homebrew):

# Add the 9n9s tap
brew tap 9n9s-io/9n9s

# Install the CLI
brew install 9n9s-cli

Linux (apt):

# Add the repository
curl -fsSL https://pkg.9n9s.com/public.key | sudo apt-key add -
echo "deb https://pkg.9n9s.com/apt stable main" | sudo tee /etc/apt/sources.list.d/9n9s.list

# Update and install
sudo apt update
sudo apt install 9n9s-cli

Linux (yum/dnf):

# Add the repository
sudo tee /etc/yum.repos.d/9n9s.repo << EOF
[9n9s]
name=9n9s Repository
baseurl=https://pkg.9n9s.com/rpm
enabled=1
gpgcheck=1
gpgkey=https://pkg.9n9s.com/public.key
EOF

# Install
sudo yum install 9n9s-cli
# Or on Fedora/RHEL 8+
sudo dnf install 9n9s-cli

Install via Binary Download

Download pre-built binaries from the releases page:

# Download for Linux
curl -L -o 9n9s-cli https://github.com/9n9s-io/9n9s-cli/releases/latest/download/9n9s-cli-linux-amd64

# Download for macOS
curl -L -o 9n9s-cli https://github.com/9n9s-io/9n9s-cli/releases/latest/download/9n9s-cli-darwin-amd64

# Download for Windows
curl -L -o 9n9s-cli.exe https://github.com/9n9s-io/9n9s-cli/releases/latest/download/9n9s-cli-windows-amd64.exe

# Make executable (Linux/macOS)
chmod +x 9n9s-cli

# Move to PATH
sudo mv 9n9s-cli /usr/local/bin/

Build from Source

# Clone the repository
git clone https://github.com/9n9s-io/9n9s-cli.git
cd 9n9s-cli

# Build with Go
go build -o 9n9s-cli ./cmd/9n9s-cli

# Install
sudo mv 9n9s-cli /usr/local/bin/

CLI Authentication

After installation, authenticate the CLI with your 9n9s account:

# Login interactively
9n9s-cli login

# Or set API key directly
export NINES_API_KEY="your-api-key"

# Verify authentication
9n9s-cli auth whoami

API Key Management:

1. Go to Organization Settings > API Keys in your dashboard
2. Click Create API Key
3. Set permissions and scope for the key
4. Copy the key and store it securely
5. Use the key for CLI authentication

Docker Integration

Use 9n9s with containerized applications and services.

Docker Images

Official Docker images are available for the CLI tool:

# Pull the latest CLI image
docker pull 9n9s/cli:latest

# Use in a container
docker run --rm -e NINES_API_KEY="your-api-key" 9n9s/cli:latest heartbeat pulse your-monitor-id

Docker Compose Example

docker-compose.yml

version: "3.8"

services:
    app:
        build: .
        environment:
            - NINES_HEARTBEAT_ID=your-monitor-id
        depends_on:
            - monitor-health

    monitor-health:
        image: 9n9s/cli:latest
        environment:
            - NINES_API_KEY=${NINES_API_KEY}
        command: |
            sh -c '
              while true; do
                sleep 300
                9n9s-cli heartbeat pulse ${NINES_HEARTBEAT_ID} --message "Health check from container"
              done
            '
        restart: unless-stopped

Kubernetes Integration

Deploy monitoring alongside your Kubernetes applications:

kubernetes-monitoring.yaml

apiVersion: batch/v1
kind: CronJob
metadata:
    name: health-monitor
spec:
    schedule: "*/5 * * * *" # Every 5 minutes
    jobTemplate:
        spec:
            template:
                spec:
                    containers:
                        - name: health-check
                          image: 9n9s/cli:latest
                          env:
                              - name: NINES_API_KEY
                                valueFrom:
                                    secretKeyRef:
                                        name: monitoring-secrets
                                        key: api-key
                              - name: NINES_HEARTBEAT_ID
                                value: "your-monitor-id"
                          command:
                              - /bin/sh
                              - -c
                              - |
                                  # Check application health
                                  if kubectl get pods -l app=myapp --field-selector=status.phase=Running | grep -q myapp; then
                                    9n9s-cli heartbeat pulse $NINES_HEARTBEAT_ID --message "Application pods healthy"
                                  else
                                    9n9s-cli heartbeat pulse $NINES_HEARTBEAT_ID --fail --message "Application pods unhealthy"
                                  fi
                    restartPolicy: OnFailure

Configuration as Code

Set up Infrastructure as Code for your monitoring configuration.

Terraform Provider

Install and configure the 9n9s Terraform provider:

main.tf

terraform {
  required_providers {
    nines = {
      source  = "9n9s-io/nines"
      version = "~> 1.0"
    }
  }
}

provider "nines" {
  api_key = var.nines_api_key
  # Or use environment variable NINES_API_KEY
}

# Example monitor configuration
resource "nines_project" "production" {
  name            = "Production Services"
  organization_id = var.organization_id
}

resource "nines_heartbeat_monitor" "backup_job" {
  name           = "Daily Database Backup"
  project_id     = nines_project.production.id
  schedule       = "0 2 * * *"
  grace_period   = "1h"
  timezone       = "UTC"

  tags = {
    environment = "production"
    service     = "database"
    criticality = "high"
  }
}

Pulumi Integration

Use Pulumi for TypeScript/Python Infrastructure as Code:

TypeScript:

import * as nines from "@9n9s/pulumi";

const project = new nines.Project("production", {
    name: "Production Services",
    organizationId: "your-org-id",
});

const backupMonitor = new nines.HeartbeatMonitor("backup-job", {
    name: "Daily Database Backup",
    projectId: project.id,
    schedule: "0 2 * * *",
    gracePeriod: "1h",
    timezone: "UTC",
    tags: {
        environment: "production",
        service: "database",
        criticality: "high",
    },
});

Python:

import pulumi_nines as nines

project = nines.Project("production",
    name="Production Services",
    organization_id="your-org-id"
)

backup_monitor = nines.HeartbeatMonitor("backup-job",
    name="Daily Database Backup",
    project_id=project.id,
    schedule="0 2 * * *",
    grace_period="1h",
    timezone="UTC",
    tags={
        "environment": "production",
        "service": "database",
        "criticality": "high"
    }
)

YAML Configuration

Use YAML files for simple configuration management:

9n9s.yml

api_version: v1
kind: Configuration

projects:
    production-services:
        name: "Production Services"
        description: "Critical production infrastructure monitoring"

        heartbeats:
            - name: "Daily Database Backup"
              schedule: "0 2 * * *"
              grace_period: "1h"
              timezone: "UTC"
              tags:
                  environment: production
                  service: database
                  criticality: high

            - name: "Log Rotation"
              schedule: "0 1 * * 0" # Weekly on Sunday
              grace_period: "30m"
              expected_runtime:
                  min: "5m"
                  max: "20m"
              tags:
                  environment: production
                  service: system
                  criticality: medium

        uptime:
            - name: "API Health Check"
              url: "https://api.example.com/health"
              frequency: "1m"
              assertions:
                  - type: "STATUS_CODE"
                    operator: "EQUALS"
                    value: "200"
                  - type: "RESPONSE_TIME"
                    operator: "LESS_THAN"
                    value: "1000"
              tags:
                  environment: production
                  service: api
                  criticality: high

Apply the configuration:

# Preview changes
9n9s-cli config diff --file 9n9s.yml

# Apply changes
9n9s-cli config apply --file 9n9s.yml

Environment Variables

Configure 9n9s tools using environment variables:

# API Authentication
export NINES_API_KEY="your-api-key"

# Default Organization/Project
export NINES_ORGANIZATION_ID="your-org-id"
export NINES_PROJECT_ID="your-project-id"

# CLI Configuration
export NINES_CONFIG_DIR="$HOME/.config/9n9s"
export NINES_LOG_LEVEL="info"  # debug, info, warn, error

# SDK Configuration
export NINES_TIMEOUT="10s"
export NINES_RETRY_COUNT="3"
export NINES_BASE_URL="https://api.9n9s.com"  # For on-premise deployments

Verification

Verify your installation is working correctly:

Test SDK Installation

Python:

from nines import Nines
print("9n9s Python SDK installed successfully!")

# Test connection (optional)
nines = Nines("test-id")
print(f"SDK version: {nines.version}")

Node.js:

import { Nines } from "@9n9s/sdk";

console.log("9n9s Node.js SDK installed successfully!");

// Test connection (optional)
const nines = new Nines("test-id");
console.log(`SDK version: ${nines.version}`);

Test CLI Installation

# Check version
9n9s-cli version

# Test authentication
9n9s-cli auth whoami

# List projects (requires authentication)
9n9s-cli projects list

Test Monitoring

Create a test monitor and send a pulse:

# Create a test heartbeat monitor
MONITOR_ID=$(9n9s-cli heartbeat create \
  --name "Test Monitor" \
  --schedule "every 5 minutes" \
  --grace 300 \
  --project-id "your-project-id" \
  --output json | jq -r '.id')

# Send a test pulse
9n9s-cli heartbeat pulse $MONITOR_ID --message "Test pulse from CLI"

# Check monitor status
9n9s-cli heartbeat get $MONITOR_ID

Next Steps

Now that you have 9n9s installed and configured:

1. Create your first monitor - Set up monitoring for a real service
2. Configure alerts - Get notified when issues occur
3. Set up team access - Invite team members and configure permissions
4. Explore integrations - Connect with your existing tools and workflows

Troubleshooting

Common Installation Issues

SDK Import Errors:

• Ensure you’re using the correct package name for your language
• Check that your Python/Node.js version meets minimum requirements
• Verify the SDK is installed in the correct environment/virtual environment

CLI Authentication Issues:

• Verify your API key has the correct permissions
• Check that the API key hasn’t expired
• Ensure you’re using the correct organization context

Network Connectivity:

• Verify you can reach api.9n9s.com and pulse.9n9s.com
• Check firewall rules and proxy settings
• Ensure TLS/SSL certificates are up to date

Permission Errors:

• Check that your API key has sufficient permissions for the operations you’re attempting
• Verify you have access to the specified organization and projects
• Contact your organization administrator if you need additional permissions

Getting Help

• Documentation: docs.9n9s.com
• Community: GitHub Discussions
• Support: [email protected]
• Status Page: status.9n9s.com