DEV Community: Jonathan Mourtada

OpenTelemetry tracing with nodejs and express

Jonathan Mourtada — Fri, 11 Feb 2022 00:00:00 +0000

In this post I’ll go through a simple example on how to setup OpenTelemetry tracing in a nodejs express application.

Hello world express

// index.js
const express = require("express");

const app = express();
const port = 3000;

app.get("/", (req, res) => {
  res.send("Hello World!");
});

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`);
});

Needed packages

First we need to add the OpenTelemetry api and sdk package

yarn add @opentelemetry/api @opentelemetry/sdk-node

To instrument express, incoming and outgoing http requests we use the express and http instrumentation libraries.

yarn add @opentelemetry/instrumentation-http @opentelemetry/instrumentation-express

And lastly we add the otlp grpc tracing exporter.

yarn add @opentelemetry/exporter-trace-otlp-grpc

Setup tracing

// tracing.js
const OpenTelemetry = require("@opentelemetry/sdk-node");
const Resources = require("@opentelemetry/resources");
const SemanticConventions = require("@opentelemetry/semantic-conventions");
const InstrumentationHttp = require("@opentelemetry/instrumentation-http");
const InstrumentationExpress = require("@opentelemetry/instrumentation-express");
const ExporterTraceOtlpGrpc = require("@opentelemetry/exporter-trace-otlp-grpc");

const sdk = new OpenTelemetry.NodeSDK({
  resource: new Resources.Resource({
    [SemanticConventions.SemanticResourceAttributes.SERVICE_NAME]: "my-service",
  }),
  traceExporter: new ExporterTraceOtlpGrpc.OTLPTraceExporter({
    // url is optional and can be omitted - default is localhost:4317
    url: process.env["OTEL_EXPORTER_OTLP_ENDPOINT"] || undefined,
  }),
  instrumentations: [
    new InstrumentationHttp.HttpInstrumentation(),
    new InstrumentationExpress.ExpressInstrumentation(),
  ],
});

sdk.start();

Run the express server

To configure and start the tracing sdk we can use nodes -r/--require flag to preload our tracing module.

node -r ./tracing.js index.js

Now every request will be traced and exported to the configured otlp receiver.

Create a simple azure function

Jonathan Mourtada — Sat, 05 Feb 2022 00:00:00 +0000

In this post I’ll show you how to create a simple azure function which is triggered by a http call and logs the requests to an appendblob on azure blob storage.

Create a new project

First of all you will need to create a project. I just used the visual studio project template for azure functions(The Azure SDK is needed). Choose to create a Http trigger function and set the authorization level to anonymous

The code

Once created you will get a stub for a working http trigger function. Below is an example how to log the request to an appendblob.

using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using Azure.Storage.Blobs;
using System.Globalization;
using Azure.Storage.Blobs.Specialized;
using Azure.Storage.Blobs.Models;
using System.Text;
using Microsoft.Extensions.Primitives;
using System.Linq;

namespace MyAzureFunction
{
  public static class MyAzureFunction
    {
    [FunctionName("MyAzureFunction")]
    public static async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = null)] HttpRequest req,
    [Blob("my-blob-container")] BlobContainerClient container,
    ILogger log)
    {
      var culture = new CultureInfo("sv-SE");
      var clientIp = GetClientIp(req.Headers);

      var logStr = $"{DateTime.Now.ToString("T", culture)} {clientIp}\n";
      log.LogInformation(logStr);

      await container.CreateIfNotExistsAsync();
      var blobName = $"access_{DateTime.Now.ToString("d", culture).Replace("-", "")}.log";
      var appendBlob = container.GetAppendBlobClient(blobName);
      await appendBlob.CreateIfNotExistsAsync();
      await appendBlob.SetHttpHeadersAsync(new BlobHttpHeaders() { ContentType = "text/plain" });
      byte[] blockContent = Encoding.UTF8.GetBytes(logStr);
      using (var ms = new MemoryStream(blockContent))
      {
        await appendBlob.AppendBlockAsync(ms);
      }

      return new OkResult();
    }

    private static string GetClientIp(IHeaderDictionary headers)
    {
      headers.TryGetValue("X-Forwarded-For", out StringValues value);
      var clientIp = value.FirstOrDefault() ?? "missing-ip";
      return clientIp;
    }
  }
}

The first interesting part is the [Blob("my-blob-container")] BlobContainerClient container. This injects a BlobContainerClient that will be used with our interactions with the blob storage of our configured azure storage account.

It is important to use the new Azure.Storage.Blobs namespace. I had some troubles following old code examples that used deprecated namespaces and types. More information can be found here https://docs.microsoft.com/en-us/azure/azure-functions/functions-bindings-storage-blob-output?tabs=csharp#additional-types.

The function creates an appendblob for every new date and sets the content-type of the blob to text/plain. It then adds a row to the blob for every incoming http get request.

How to setup OpenTelemetry instrumentation in ASP.NET core

Jonathan Mourtada — Sun, 30 Jan 2022 00:00:00 +0000

In this post I’ll show how to setup OpenTelemetry tracing, metrics and logging for AspNetCore on dotnet 6

New project

Start by creating a new project. I’ll be using the webapi template.

dotnet new webapi --output opentelemetry-example

Add required packages

Then we need to add the OpenTelemetry packages.

dotnet add package --prerelease OpenTelemetry.Exporter.Console
dotnet add package --prerelease OpenTelemetry.Extensions.Hosting
dotnet add package --prerelease OpenTelemetry.Instrumentation.AspNetCore

The first package is the console exporter which is for outputing telemetry data on to your local developer console. For a real project you would probably use something like the jaeger or the otlp exporter.

The Extension.Hosting package includes the extension methods AddOpenTelemetryTracing and AddOpenTelemetryMetrics which is used on IServiceCollectionto setup OpenTelemetry. It also adds the LoggingBuilder extension method AddOpenTelemetry.

The Instrumentation.AspNetCore package collects telemetry data about incoming web requests. It provides the AddAspNetCoreInstrumentation extension method for TraceProviderBuilder and MeterProviderBuilder

Add tracing

builder.Services
    .AddOpenTelemetryTracing((builder) => builder
        // Configure the resource attribute `service.name` to MyServiceName
        .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("MyServiceName"))
        // Add tracing of the AspNetCore instrumentation library
        .AddAspNetCoreInstrumentation()
        .AddConsoleExporter()
    );

Add metrics

builder.Services
    .AddOpenTelemetryMetrics(builder => builder
        // Configure the resource attribute `service.name` to MyServiceName
        .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("MyServiceName"))
        // Add metrics from the AspNetCore instrumentation library
        .AddAspNetCoreInstrumentation()
        .AddConsoleExporter(options =>
        {
            options.MetricReaderType = MetricReaderType.Periodic;
            options.PeriodicExportingMetricReaderOptions.ExportIntervalMilliseconds = 5000;
        }));

Add logging

builder.Host
    .ConfigureLogging(logging => logging
        .ClearProviders()
        .AddOpenTelemetry(options =>
        {
            // Export the body of the message
            options.IncludeFormattedMessage = true;
            // Configure the resource attribute `service.name` to MyServiceName
            options.SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("MyServiceName"));
            options.AddConsoleExporter(options =>
            {
                options.MetricReaderType = MetricReaderType.Periodic;
                options.PeriodicExportingMetricReaderOptions.ExportIntervalMilliseconds = 5000;
            });
        }));

Complete example

using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Services
    .AddOpenTelemetryTracing((builder) => builder
        // Configure the resource attribute `service.name` to MyServiceName
        .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("MyServiceName"))
        // Add tracing of the AspNetCore instrumentation library
        .AddAspNetCoreInstrumentation()
        .AddConsoleExporter()
    );

builder.Services
    .AddOpenTelemetryMetrics(builder => builder
        // Configure the resource attribute `service.name` to MyServiceName
        .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("MyServiceName"))
        // Add metrics from the AspNetCore instrumentation library
        .AddAspNetCoreInstrumentation()
        .AddConsoleExporter(options =>
        {
            options.MetricReaderType = MetricReaderType.Periodic;
            options.PeriodicExportingMetricReaderOptions.ExportIntervalMilliseconds = 5000;
        }));

builder.Host
    .ConfigureLogging(logging => logging
        .ClearProviders()
        .AddOpenTelemetry(options =>
        {
            // Export the body of the message
            options.IncludeFormattedMessage = true;
            // Configure the resource attribute `service.name` to MyServiceName
            options.SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("MyServiceName"));
            options.AddConsoleExporter(options =>
            {
                options.MetricReaderType = MetricReaderType.Periodic;
                options.PeriodicExportingMetricReaderOptions.ExportIntervalMilliseconds = 5000;
            });
        }));

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Add an Azure static disk with Azure disk CSI driver in Kubernetes

Jonathan Mourtada — Fri, 21 Jan 2022 00:00:00 +0000

The in tree storage drivers for Kubernetes is planned to be removed in version 1.26-1.27. The new Container Storage Interface(CSI) is the way forward for handling persistent storage inside Kubernetes and it’s been GA since 1.13. For Azure disk the in tree driver is deprecated since 1.19.

Recently I’ve setup a new AKS cluster and the documentation how to setup and azure static disk volume with Azure disk CSI was a bit hard to find. So I’ll document how I did here.

Create the static disk

The official docs recommends to create disk in the node resource group of your AKS cluster.

az disk create \
--resource-group my-node-resource-group \
--name disk-aks-something \
--location swedencentral \
--os-type linux \
--sku Premium_LRS \
--size-gb 8 \
--query id --output tsv

This command will output the disk id that you’ll use for as the volumeHandle in the next step.

Add the persistent volume

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-my-volume
spec:
  capacity:
    storage: 8Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  csi:
    driver: disk.csi.azure.com
    readOnly: false
    volumeHandle: /subscriptions/subscription-id/my-node-resource-group/my-resource-group/providers/Microsoft.Compute/disks/disk-aks-something
    volumeAttributes:
      fsType: ext4
      #partition: "1" # optional, remove this if there is no partition

Add the persistent volume claim

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: pvc-my-volume
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 8Gi
  volumeName: pv-my-volume
  storageClassName: ""

Add the pvc to your pod

kind: Pod
apiVersion: v1
metadata:
  name: nginx-azuredisk
spec:
  nodeSelector:
    kubernetes.io/os: linux
  containers:
    - image: mcr.microsoft.com/oss/nginx/nginx:1.17.3-alpine
      name: nginx-azuredisk
      command:
        - "/bin/sh"
        - "-c"
        - while true; do echo $(date) >> /mnt/azuredisk/outfile; sleep 1; done
      volumeMounts:
        - name: azuredisk01
          mountPath: "/mnt/azuredisk"
  volumes:
    - name: azuredisk01
      persistentVolumeClaim:
        claimName: pvc-my-volume

And that’s it!

How to deploy an aks cluster in azure

Jonathan Mourtada — Thu, 13 Jan 2022 00:00:00 +0000

This is a guide on how to deploy a kubernetes cluster in azure(AKS). The steps below is done with az cli in a bash terminal.

Creating a resource group

First of all we need a resource group. This is where our kubernetes cluster will be created together with our custom vnet.

az group create --name rg-something-swedencentral-01 --location swedencentral

Creating a custom vnet

Then we’ll create our own vnet so we can have control over the assigned IP adresses. The vnet can be created automatically if you don’t have any need for specifying your own subnets. But if you want to have a hybrid cloud connected to a on premise network you need to make sure the cloud network and on premise network doesn’t collide.

To create the vnet run:

az network vnet create --name vnet-something-swedencentral-01 --resource-group rg-something-swedencentral-01 --address-prefixes 10.110.0.0/16

Then we create a subnet used for our aks cluster. This subnet is used for both our nodes and pods. It’s important to have enough adresses for the cluster. If you grow out of your subnet the cluster must be recreated.

az network vnet subnet create --resource-group rg-something-swedencentral-01 --vnet-name vnet-something-swedencentral-01 --name snet-something-swedencentral-aks-01 --address-prefixes 10.110.0.0/22

Create a user assigned managed identity

To use our newly created vnet and subnet the aks cluster needs to have permission to use it. Aks uses a service principal when it calls the azure api:s. A service principal is just a appid with a secret. A service principal secret by default expires after one year and you need to renew the secret. But you can also use a managed identity. A managed identity is a service principal which azure automically renews the secret every 46 days.

To create a managed identity run:

az identity create --resource-group rg-something-swedencentral-01 --name id-aks-something-swedencentral-01

The we need to create a role assigment to our subnet with the role Network Contributor

# Get the id of the subnet
SUBNET_ID=$(az network vnet subnet list \
    --resource-group rg-something-swedencentral-01 \
    --vnet-name vnet-something-swedencentral-01 \
    --query "[0].id" --output tsv)

# Get the appid of the managed identity
APP_ID=$(az identity show --resource-group rg-something-swedencentral-01 --name id-aks-something-swedencentral-01 --query "clientId" --output tsv)

# Create the role assignment
az role assignment create --assignee $APP_ID --scope $SUBNET_ID --role "Network Contributor"

Create the aks cluster

To create the cluster we need to run the command below.

az aks create \
--resource-group rg-something-swedencentral-01 \
--name aks-something-swedencentral-01 \
--location swedencentral \
--enable-managed-identity \
--assign-identity $APP_ID \
--network-plugin azure \
--vnet-subnet-id $SUBNET_ID \
--docker-bridge-address 172.17.0.1/16 \
--dns-service-ip 10.96.0.10 \
--service-cidr 10.96.0.0/16 \
--windows-admin-username windowsuser \
--windows-admin-password 'windowspassword' \
--api-server-authorized-ip-ranges <ALLOW_CIDR_RANGE> \
--node-vm-size Standard_D2s_v3 \
--node-count 2 \
--node-resource-group rg-aks-something-swedencentral-01

I’ll go through some of the parameters.

network-plugin

Aks has two network plugins kubenet and azure cni. Kubenet is fully isolated NAT network and doesn’t support bringing your own vnet. Azure cni is required for windows nodes and if you want to have your own vnet.

service-cidr

This is a network that only resides inside the cluster. It’s used by kubernetes services. This ip-range cannot be accessible anywhere else in your network. But the network can be reused inside another kubernetes cluster.

windows-admin-username and windows-admin-password

This is only needed if you want to run windows nodes in you cluster.

api-server-authorized-ip-ranges

Azure support both public and private cluster. A private cluster means you have to have a vpn or hybrid cloud setup to manage your kubernetes cluster. A public cluster is by default accessible anywhere. With this parameter you can lock down which ip ranges that have access.

node-resource-group

This parameter sets the name of the automatic created node resource group. This resource group is always created and is managed by the kubernetes cluster.

The OpenTelemetry collector

Jonathan Mourtada — Sat, 08 Jan 2022 00:00:00 +0000

The OpenTelemetry collector provides a vendor-agnostic implementation on how to receive, process and export telemetry data. The collector is a single binary that can be run as an agent or a gateway.

Versions of the collector

There are two versions of the collector. The core version contains components that are the foundation of the collector such as configuration and the most common receivers, processors and exporters. The contrib version contains all of the components of core but also more vendor-specific and experimental receivers, processors and exporters.

Collector components

Receivers

A receiver is how data gets into the collector. Data can either be pushed or pulled. One receiver can support multiple data sources(traces, metrics and logs). An example of a receiver is an OpenTelemetry Protocol(OTLP) endpoint or a prometheus scraper.

Exporters

Exporters sends data to one or more backends/destinations. Like the receiver an exporter can also be push or pull based and support multiple data sources. For example an exporter could provide a prometheus endpoint or send data to a jaeger backend.

Processors

Processors handles data after it’s received but before it’s exported. An example of a processor is the batch processor which puts incoming data in batches. This makes for better compressing of the data and limits the number of outgoing connections.

What is OpenTelemetry?

Jonathan Mourtada — Tue, 04 Jan 2022 00:00:00 +0000

This is the first post in a planned blog series about OpenTelemetry.

OpenTelemetry is an open source observability framework which is the result of merging the projects OpenTracing and OpenCensus. It’s goal is to provide language agnostic tools for telemetry data such as tracing, metrics and logging in distributed architectures.

Signals

The architecture of OpenTelemetry is designed around signals and can be thought of as categories of telemetry. Each signal provides a way for software to describe itself.

There are four signals defined in the specification:

Tracing
Metrics
Logs
Baggage

Tracing

A trace tracks the progress of an request as it’s flows through services in a distributed application. A trace contains a tree of spans. A span represents a unit of work for example in a service or a component.

Metrics

A metric is measurement of work being done by a service or a component in a specific point in time. An example of a metric can be a counter of total requests for a http endpoint.

Logs

A log entry is a text record that has a timestamp. Logs is an independant data source but can also be attached to spans.

Baggage

Bagagge is a mechanism for propagating observability events as name/value pairs in a distributed transaction. This can be used to store data about a trace across process-boundaries.

Context propagation

Signals are built on shared a mechanism called context propagation. The context provides a way to store state and accessing data over the lifetime of a distributed transaction. Propagators are used to serialize and deserialize context over different protocols.

Debug x86 assembly with GDB

Jonathan Mourtada — Sat, 04 Dec 2021 00:00:00 +0000

This is the sixth post about x86 assembly. In this post I will show how to debug your x86 assembly code with the GNU Project debugger(GDB). GDB can be used with a lot of languages for example assembly, C, C++ and Rust.

Generating debug symbols

First of all you need to tell nasm to generate debug information. This is done with -g and -F dwarf. The -g option tells nasm to generate debug information and the -F dwarf sets the debugging format to the standardized debugging format DWARF.

Start GDB

Start gdb with gdb <your_assemlby_program> to enter its interactive shell. You can set breakpoints by writing break <function_name or line number>. By default gdb uses AT&T flavor to change to intel flavor type set dissambly-flavor intel. To start debugging the program type run.

Debugging the program

The program will run until a crash happens or to any breakpoint you set and pause. If you want to look at the values currently in the registers type info registers or if you want to see the next instructions at the same time as the value of the registers type layout regs.

To execute the next instruction type next. If you want to step into a function call type step. If the program crashes gdb will tell you which line that was the last one executing. You can type backtrace to see the full stack trace

Calling functions in x86 assembly

Jonathan Mourtada — Tue, 23 Nov 2021 00:00:00 +0000

This is the fifth post about x86 assembly. In this post I will show how to call functions in x86 assembly.

Below is a simple program that has three functions besides main.

global main
extern printf
section .text
main:
        mov rdi, 5
        call times2
        mov rdi, rax
        call print_value
        call exit
times2:
        push rbp
        mov rbp, rsp

        mov rax, rdi
        add rax, rax

        mov rsp, rbp
        pop rbp
        ret
print_value:
        push rbp
        mov rbp, rsp

        push rdi
        mov rdi, fmt
        pop rsi
        mov rax, 0
        call printf wrt ..plt

        mov rsp, rbp
        pop rbp
        ret
exit:
        mov rdi, 0 ; exit code 0
        mov rax, 60 ; system call for exit
        syscall

section .data
fmt: db "The value is %d", 10, 0

Passing values to functions

The code above is following the Linux 64-bit ABI where the first six arguments(integers and pointers) are passed through registers. You could also pass the arguments on the stack or hardcoded memory locations.

Function prologue and epilogue

The beginning and the end in the functions times2 and print_value is called the function prologue and epilogue.

  push rbp
  mov rbp, rsp

  ...

  mov rsp, rbp
  pop rbp
  ret

This a convention for preparing the stack for usage. The prologue creates a new stack frame for the called function and the epilogue restores the stack frame for the calling function.

Calling printf from the C standard library in assembly

Jonathan Mourtada — Thu, 11 Nov 2021 00:00:00 +0000

This is the fourth post about x86 assembly. In this post I will show an example how to call the printf function from the C standard library in assembly code.

section .text
    default rel
    extern printf
    global main
main:
    ; Create a stack-frame, re-aligning the stack to 16-byte alignment before calls
    push rbp

    mov rdi, fmt
    mov rsi, message
    mov rax, 0

    ; Call printf
    call printf wrt ..plt

    pop rbp ; Pop stack

    mov rax,0   ; Exit code 0
    ret ; Return
section .data
    message: db "Hello, World", 10, 0
    fmt: db "%s", 10, 0


$ nasm printf.asm -f elf64 -o printf.o
$ gcc printf.o
$ ./a.out
# Hello world

The first part

  default rel
  extern printf
  global main

The default rel is a nasm assembly directive. It tells nasm to use rip relative adressing. In short this makes the assembler to rewrite the references in instructions that uses our fmt and message constants relative to the instruction pointer. This is needed because default for the linker in 64-bit linux is to use position-independent code.

The extern printf part tells the assembler that this symbol exists outside of this file and needs to be referenced at a later stage.

Last row here is global main which is needed for gcc and it’s the entry point for libc.

main

First we need to align the stack because the x86_64 ABI requires the stackpointer to always be 16-byte aligned so therefor we push a value to it.

Then we prepare our registers for the function call to printf and then we call printf wrt ..plt. What happens here is that we load printf from the libc shared library and this is a little bit complicated but very briefly it says call printf with relation to procedure linkage table. The PCL will then the first time printf is called resolve where printf is in memory with the help of the dynamic link loader in linux. It then stores that adress for future calls. We could link printf statically which would copy the code of printf into the executable.

Lastly we need to set return value of main to zero and do a ret.

call and ret

When you do a call operation two things happen. First the instruction on the next instruction is pushed onto the stack. In our example above it will be the memory adress of the instruction pop rbp. Secondly it will jump to the memory adress where printf starts. When printf is done it will do a ret instruction which will pop our memory adress from the stack and jump back to our main function.

x86 CPU registers

Jonathan Mourtada — Sat, 06 Nov 2021 00:00:00 +0000

This is the third post about x86 assembly. In the previous post I went through every line of a minimal assembly program. In this post I will briefly explain some of the x86 CPU registers.

General purpose registers

Most of the work of a CPU is to process data. But reading and storing data from memory slows down the processor. Therefore the processor has storage of it’s own called registers. There are 16 64-bit registers in the x86 architecture.

rax
rcx
rdx
rbx
rsi
rdi
rsp
rbp
r8-r15

These registers are used for inputs and outputs for different CPU instruction. For example in the application binary interface(ABI) for linux 64-bit the rax register is used for specifying the syscall number and it’s also used for storing the return value of functions. The arguments for a function is then stored in order rdi(arg1), rsi(arg2), rdx(arg3) and so on. If there are more arguments than six they are stored on the stack.

The image below shows the calling conventions for syscalls on different CPU architectures for linux 64-bit.

Special purpose registers

While the values stored in a general purpose register has no special meaning to the processor, special purpose registers holds state about the program.

Here are examples of special purpose registers:

rsp - Stores the memory adress to the top of the stack
rbp - Stores the memory adress to the current stack frame
rip - Stores the memory adress of the next instruction to execute
rflags - Here the CPU stores information about the result of arithmetic instructions. For example comparing numbers.

A minimal assembly program

Jonathan Mourtada — Fri, 29 Oct 2021 00:00:00 +0000

This is the second post about x86 assembly. In the previous post I described how to compile a hello world program. In this post i will go through and even smaller program.

Minimal example

          global _start

          section .text
_start: mov rax, 60 ; system call for exit
          mov rdi, 0 ; exit code 0
          syscall ; invoke operating system to exit

This programs doesn’t print any output and only sets an exit code. If the program doesn’t set an exit code the program will crash with a Segmentation fault error.

Sections

There is only one section in this program called .text. Here you put your source code which is readonly when the program is ran. Sections is used by the assembler to group data and code in different locations in memory. For example in the hello world example we had a section called .data which we initialized a constant sequence of bytes.

Labels

There is also only one label in this program called _start. A label can be seen as pointer to an instruction in memory. A label can then be used as a reference in code to run a specific block of code(almost like a function call). The label _start has a special meaning for the linker ld and that is where an executable will start executing instructions.

Global keyword

The global keyword tells the assembler that this label should be able to be referenced outside of this assembly file. It’s mostly like exporting a function in high level languages.

Instructions

The syntax for operations is opcode <operand>, <operand>. We first have an opcode which tells the cpu what we want to do and with which operands.

The instruction mov rax, 60 tells the CPU to move the decimal constant value 60 to a CPU general-purpose register called rax. When an operand is constant value like above it’s called immediate addressing. CPU registers are small high-speed memory locations in the CPU.

Syscall

The syscall is a special operation that tells the CPU that the program wants to talk to the operating system. The program halts and the operating system takes over and reads the rax register for the syscall number which in linux 64bit is the syscall for exit. The rdi register where we put 0 holds the value for the exit code. When a syscall is done the program usually resumes executing but not in this case as we told the operating system that we wanted to exit.