Another rule. Another example. Another edge case paragraph.

The prompt grows from a few hundred tokens to thousands, then tens of thousands. And somehow the agent gets worse - it forgets rules from the top, applies the wrong convention, or just ignores half of what you wrote.

The problem isn't missing instructions. The problem is architectural.

The Monolithic Prompt Trap

Most people start with a single system prompt that tries to cover everything: code style, git conventions, testing standards, ticket management, deployment rules, error handling patterns.

It works fine at first. Then the project grows, the team adds more conventions, and suddenly you're maintaining a 10-page document that the model has to reason over for every single request.

This is the equivalent of putting your entire application logic in one file. It works until it doesn't.

LLMs have finite attention. The more context you load, the less reliably the model attends to any specific part of it. Research on this is clear - performance degrades as context grows, especially for instructions in the middle of long prompts.

You're not giving the agent more knowledge.

You're giving it more noise.

Skills as Modular Units

Instead of one massive prompt, break your instructions into self-contained modules - call them skills, rules, playbooks, whatever fits your setup.

Each one covers exactly one domain:

• git workflow conventions

• code style for your language

• how to interact with your ticket system

• testing standards

Each skill has two properties:

• A trigger condition: when should this knowledge be active? A git workflow skill is irrelevant when the user asks about database migrations. A Java code style skill is irrelevant when the task is creating a Jira ticket.

• A focused scope: it contains everything the agent needs for that domain, and nothing else.

The key insight: skills are loaded on demand, not all at once. When someone asks the agent to create a merge request, it loads the git workflow skill. When someone asks to implement a feature, it loads the code quality and language-specific skills.

The active context stays small and relevant.

THis isn't a new idea. It's the same principle behind modular software design - high cohesion, low coupling. Each module knows its domain deeply and doesn't leak into others.

The Router, Not the Brain

If skills are modules, you need something to route between them. This is a lightweight orchestrator - a small set of instructions that knows what skills exist and when to load them. It doesn't contain domain knowledge itself. It's a lookup table.

Think of it as an API gateway for your agent's knowledge. The gateway doesn't process business logic. It takes at the incoming request and forwards it to the right service.

In practice, this means your base prompt is tiny. It contains:

• A list of available skills with their trigger conditions

• Rules for when to load which skill

• Delegation logic for which agent handles which domain

Everything else lives in the skills themselves, loaded only when needed.

Split Agents by Domain

The same principle applies to agents themselves. A single agent with every tool and every piece of context is the prompt equivalent of a god object. It can do everything, which means it does nothing reliably.

Instead, split by domain. One agent handles ticket management. Another handles git operation. Another handles code implementation. Each gets only the tools and context relevant to its job.

This has a practical benefit beyond context size: agents can chain. The code agent writes the implementation, then delegates the commit to the git agent. The git agent doesn't need to know about the code style. The code agent doesn't need to know about commit message convention. Each operates within its domain.

Delegation rules should be explicit. URL patterns, keyword triggers, tool categories - whatever majkes the routing unambiguous. When the boundaries are clear, the agent doesn't have to guess which hat to wear.

What You Actually Get

Smaller active context. Instead of 50k tokens always loaded, you load 2-5k per skillm only when relevant. The model reasons over focused information instead of scanning a wall of text.

Predictability. Each skill is testable in isolation. You can verify that your git workflow skill produces correct branch names without woryying about Go convention interfering. When something breaks, you know which skill to look at.

Composability. Skills can be shared across projects. A new repository gets the same quality standards by importing the same skill files. Teams standardize without facing everyone into one monolithic prompt.

Maintainability. Adding a new conventions means editing a skill file, not hunting through a 10-page document hoping you don't break something else. Skills can have clear ownership - the backend team maintains language-specific skills, the platform team maintains git and deployments skills.

How to Start

Audit your current prompt. Read through it and highlight where topics change. Every topic boundary is a candidate for extraction into a separate skill/

Extract each domain into its own file. One file per domain. Give each a clear trigger condition - a simple sentence describing when this skill should be active.

Build a minimal router. Your base prompt becomes a table: "when the task involves X, load skill Y". Nothing more.

Add delegation rules if you use multiple agents. Map tool categories to agents. Make the boundaries explicit.

Iterate by diagnosing, not appending. When the agent misbehaves, dob't add another paragraph. Ask: which skill should have handled this? Was it loaded? Was the trigger condition wrong? Was the skill content unclear? The fix is almost alsways in one specific skill, not in "more instructions".

The Mental Shift

The instinct to write bigger prompts comes from treating the AI agent like a junior developer who needs exhaustive instructions upfront. But that mental model breaks at scale. A better model: treat the agent like a system of services, each with a clear API contract and bounded context.

You wouldn't build a microservices architecture by putting all the logic in the API gateway. Don't build an agent architecture by putting all the knowledge in the system prompt.

The next time your agent does something wrong, resist the urge to add more text. Instead, ask: is this a missing skill, a wrong trigger, or a rouitng problem? The answer will be more useful than another paragraph in an already-too-long prompt.

Hope this helps,

Cheers!

Keep the pull requests small.

It sounds obvious. Yet in many teams, pull (merge) requests regularly contain hundreds or even thousands of changed lines.

Large PRs slow down reviews, introduce more bugs, and create unnecessary friction in the development process.

Small pull requests solve most of these problems.

Let's look at why.

The Problem With Large Pull Requests

A typical large PR looks like this:

Changes:
- 2k lines modified
- 25 files changed
- feature implementation
- refactoring
- small bug fixes

When reviewers open such a PR, several things happen immediately:

• it takes a long time to understand the context (even if there's a comprehensive description)

• the reviewer gets tired halfway through

• parts of the change are reviewed superficially

• bugs slip through

Even worse, large PRs often mix multiple types of changes:

• feature implementation

• refactoring

• formatting

• dependency updates

This makes the review provess significantly harder.

What a Good Pull Request Looks Like

For example:

Changes:
- 120 lines modified
- 3 files changed
- one clearly defined change

The intention should be obvious from the title:

Add retry mechanism for payment API client

Or

Fix race condition in inventory cache refresh

A reviewer should be able to quickly answer:

• What problem does this solve?

• What changed in the code?

• Could this introduce side effects?

If the answer to these questions is clear, the PR is well srtructured.

Why Small PRs Are Better

Small pull requests bring several benefits.

Faster Reviews

Small PRs are easier to revierw, which means they get merged faster! (Time to market!)

A useful rule of thumb:

A pull request should not take more than 10-15 minutes to review.

If it does, it's probably too large ¯\_(ツ)_/¯

Better Code Quality

When changes are small:

• reviewers pay more attention

• discussions are more focused

• issues are caught earlier

Large PRs often lead to "rubber-stamp approvals" ("LGTM").

Easier Debugging

When a bug appears after deployment, smaller PRs make it mych easier to locate the cause.

Instead of searching through a massive change set, you can quickly narrow it down.

Lower Risk Deployments

Small changes mean smaller risk.

If something goes wrong:

• the rollback is easier

• the impact is limited

• the root cause is easier to identify

This is one the reasons high-performing teams deploy frequently.

Practical Tips for Keeping PRs Small

Here are a few simple habits that help.

Separate Refactoring From Features

Do not mix refactoring and features developmnet in the same PR.

Bad:

Changes:
- Add new API endpoint
- Refactor service layer

Better:

PR #1
Changes:
- Refactor service layer

PR #2
Changes:
- Add new API endpoint

Commit Early and Often

Instead of building a huge branch over several days, open PRs earlier.

Even partial work can be reviewed it it's structured well.

Read more on Release Early, Release Often in my previous article.

Split Large Changes

If a change becomes too big, split it into logical steps.

Example:

PR #1
Changes: 
- Introduce new repository interface

PR #2
Changes:
- Implement PGSQL adapter

PR #3
Changes:
- Update service to use new repository

Each step is easier to understand and review. It's atomic. The discussions are stritly focused on a subject.

A Simple Rule I Follow

If a pull request feels difficult to review, it's probably too big.

In practice, I try to keep PRs:

• up to 500 lines (under 200-300 lines is a sweet spot; the <100 is a perfect PR)

• focused on one logical change

• reviewable in under 15 minutes

• clearly described

This keeps the development flow smooth and predictable.

Article Takeaway

Small pull requests are one of the easiest improvements a team can make.

They lead to:

• faster reviews

• better feedback

• fewer bugs

• smoother deployments

And the best part is that this habit requires no new tools or processes.

Just small changes.

Sources:

• LGTM memes: https://programmerhumor.io/memes/lgtm

• Code review paradox meme: https://programmerhumor.io/git-memes/looks-good-to-me-2w1a

Cheers!

Allocation rate is too high

Today we’re going to discuss how high allocation rate affects GC in Go and Java - and why it bites you differently in each language.

One problem. Two ecosystems.

The Problem: “small, short-lived objects everywhere”

Typical scenario:

• HTTP request handling

• JSON (de)serialization

• DTO → domain → response mapping

• Logging, metrics, tracing

Nothing fancy. Just a lot of:

• short-lived objects

• created fast

• discarded almost immediately

From a business PoV: normal backend code. From the GC PoV: constant pressure.

Go: Allocation Rate Directly Drives GC Frequency

In Go there’s no generational heap and the GC doesn’t assume “most objects die young”. Allocation rate is one of the primary triggers for GC work.

What this means in practice?

• More allocations → GC runs more often

• GC runs more often → more CPU stolen from your goroutines

• Even if pauses are short, total GC cost grows linearly

Important detail: Go’s GC is optimized for low latency, not for absorbing insance allocations rates.

Typical Go Failure Mode

You don’t see long pauses, instead you see:

• higher CPU usage

• lower throughput

• unexplained slowdown under load

Common assumption is: GC is concurrent, so it shouldn’t hurt. It is concurrent - but still does work, and that work scales with allocation rate.

In Go, the fix is almost always:

• reduce allocations

• reuse objects

• avoid unnecessary heap escapes

Java: Allocation Rate Fills the Young Generation

Java assumes something Go doesn’t:

Most objects die young.

That’s why Java uses a generational heap.

What happens with high allocation rate:

• Eden space fills up quickly

• Minor GCs happen frequently

• Most objects are reclaimed cheaply

As long as objects die young and there’re only a few survivors. Java handles high allocation rates surprisingly well.

Where it Goes Wrong

The problem starts when objects almost die young but survive just long enough to be promoted.

Then old generation fills up and a major GC cycles appear and pause times jump from miliseconds to seconds.

The allocation rate itself isn’t the killer. Promotion rate is.

This is why Java systems often look fine… until they suddenly don’t.

Same Problem, Different Pain

Both languages suffer - just in different ways.

Why This Matters Architecturally

This is not a micro-optimization issue. Application patterns come from:

• API design

• Data modeling

• Serialization choices

• Abstraction layers

In Go sloppy allocation patterns show up early and constantly.

In Java sloppy allocation patterns show up late and catastrophically.

Different runtime philosophy, same root cause.

One Takeaway

GC performance is mostly decided by allocation behavior, not GC algorithms

If you want predictable systems:

• measure allocation

• understand object lifetime

• treat memory like a first-class design concern

The rest - GC flags, collectors, tuning - comes after that.

Cheers!

Building one that survives real traffic, slow dependencies, deploys, and partial failures is where Go and Java start to diverge in interesting - and sometimes painful - ways.

This article is not about frameworks, annotations, or syntactic sugar. It’s about defaults, failure modes, and things that break at 2 in the morning.

Same Endpoint, Same Expectations

We’ll expose two ednpoints:

• GET /health

• GET /api/v1/items/{id}

Requirements (non-negotiable in production):

• JSON response

• request timeouts

• graceful shutdown

• bounded resource usage

• request ID propagation

Minimal HTTP Server

For Go we’re going to use the net/http package (ignore unhandled errors, it’s for the simplicity of the article):

package main

import (
    "encoding/json"
    "log"
    "net/http"
)

func main() {
    mux := http.NewServeMux()

    mux.HandleFunc("/health", func(w http.ResponseWriter, _ *http.Request) {
        w.WriteHeader(http.StatusOK)
        w.Write([]byte("ok\n"))
    })

    mux.HandleFunc("/api/v1/items/{id}", func(w http.ResponseWriter, r *http.Request) {
        id := r.PathValue("id")
        json.NewEncoder(w).Encode(map[string]string{
            "id": id,
        })
    })

    log.Fatal(http.ListenAndServe(":8080", mux))
}

FOr Java we go with the Spring Boot:

@RestController
@RequestMapping("/api/v1/items")
class ItemController {

    @GetMapping("/{id}")
    Map<String, String> getItem(@PathVariable String id) {
        return Map.of("id", id);
    }
}

@RestController
class HealthController {

    @GetMapping("/health")
    String health() {
        return "ok";
    }
}

Both work.

Both are dangerous.

The First Production Lie: “defaults are fine”

They’re not xD

Handle timeouts - the silent killers - first.

Go - explicit and unavoidable:

server := &http.Server{
    Addr:              ":8080",
    Handler:           mux,
    ReadTimeout:       5 * time.Second,
    ReadHeaderTimeout: 2 * time.Second,
    WriteTimeout:      10 * time.Second,
    IdleTimeout:       60 * time.Second,
    MaxHeaderBytes:    1 << 20,
}

If you don’t set these:

• slow clients can eat your goroutines

• you’re vulnerable to trivial DoS attacks

Java - hidden behind layers. In Spring Boot, timeouts live in configuration, not code:

server:
  tomcat:
    connection-timeout: 5s
    max-connections: 200
    threads:
      max: 200

What hurts:

• default vary by container

• engineers assume “the framework handles it” (!)

• thread pools silently saturate

Concurrency Model: Goroutines vs Threads (Where Pain Differs)

Go:

• one request → one goroutine

• cheap, but not free

• unlimited concurrency unless limit it

Java:

• one request → one thread (or virtual thread)

• thread pools introduce implicit backpressure

• starvation is a real failure mode

Worth remembering:

• Go fails by overcommitment

• Java fails by starvation

More about the concurrency comparison between both technologies you can find in the previous article - https://blog.skopow.ski/concurrency-in-go-vs-java

Backpressure: What Happens When Downstream is Slow?

This is where production systems die 💀

Go: you must build it yourself

var sem = make(chan struct{}, 100) // max 100 in-flight requests

func limit(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        select {
        case sem <- struct{}{}:
            defer func() { <-sem }()
            next.ServeHTTP(w, r)
        default:
            http.Error(w, "too many requests", http.StatusTooManyRequests)
        }
    })
}

What’s good in it: it’s explicit and predictable.

What’ bad: it’s easy to forget and every team reinvents it all over.

In Java it’s more like a backpressure by accident:

• servlet thread pool fills up

• requests queue

• latency explodes

• health checks start timing out

• Kubernetes kills the pod 💀

Virtual threads help, but do not fix slow downstreams.

Context Propagation and Cancellation

Go: cancellation is contagious (in a good way):

req, err := http.NewRequestWithContext(ctx, "GET", url, nil)

• client disconnects → context cancelled

• DB calls, HTTP calls, Kafka producers can stop

• If you propagate the context correclty

Context are your powerful friend. Use them!

Java: cancellation exists, but is optional:

• request cancellation rarely reaches DB drivers

• blocking calls ignore interrupts

• vierual threads improve ergonomics, not semantics

Reality:

• Go makes cancellation hard to avoid

• Java makes it easy to ignore

Graceful Shutdown (Where Many Apps Lie to Kube)

Go: explicit and correct by default:

go func() {
    if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
        log.Fatal(err)
    }
}()

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
<-ctx.Done()

shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
server.Shutdown(shutdownCtx)

• stop accepting requests

• wait for in-flight ones

• deterministic

In Java it’s more like a framework magic (until it isn’t).

Spring does graceful shutdown if:

• probes are configured correctly

• timeouts match Kubernetes settings

• no custom executors block shutdown

When it fails, debugging is painful.

Middleware / Filters: Order Matters More Than You Think

In Go:

• the middleware is explicit

• order is visible in code

• ugly, but honest

In Java:

• filters, interceptors, aspects

• execution order spread across annotations and configs

• someone will eventually log before request ID is set

Rule of thumb:
If you can’t draw the request flow from memory, it’s already too complex.

Observability: What You Need on Day One

Both ecosystems need the same signals:

• request count by status

• latency percentiles

• in-flight requests

• downstream dependency latency

• structured logs with request ID

Difference:

• Go forces you to add this consciously

• Java gives you 80% for free - and hides the remaining 20%

Failure Patterns You Will See In Real Life

In Go those are:

• mem spikes due to unbounded concurrency

• goroutine leaks from missing context cancellation

• accidental DoS due to missing limits

In Java:

• thread pool exhaustion

• cascading timeouts

• “CPU is low, but latency is insane”

Neither is “better”. They fail differently.

If You Do Only One Thing

Those should be your checklists:

Go checklist:

• see all HTTP timeouts

• limit in-flight requests

• propagate context everywhere

• implement graceful shutdown

• expose basic metrics

Java checklist:

• cap thread pools intentionally

• align server + Kubernetes timeouts

• monitor queue length, not just CPU

• test shutdown under load

• don’t trust defaults blindly

Final Thoughts

Go makes danger visible.
Java makes danger comfortable.

Both can build excellent HTTP servers - but only if you understand how they fail, not how they start.

Sources

The complete Go server with all the good practices described today you can find - as always - in the K.I.S.S. repository:

• https://github.com/flashlabs/kiss-samples/tree/main/http-server-go-v-java

Go gives us goroutines and channels. Java gives us executors, futures and virtual threads.

Different tools, different syntax… and the same mistakes.

This article is not about benchmarks or language wars ;-) It’s about the real concurrency bugs in production systems - both in Go and in Java.

Concurrency is Not Parallelism (Still)

This mistake never goes away.

• Concurrency is about structuring work.

• Parallelism is about executing work at the same time.

We’ve discussed the Concurrency is not Parallelism recently, but - as a reminder - you can write highly concurrent code that:

• runs on a single core

• blocks on I/O

• performs worse than a sequential version

How this shows up?

• Go: “Goroutines are cheap, so I’ll just spawn one per request”

• Java: “Virtual threads are lightweight, so I don’t need to think about limits anymore”

Both are wrong for the same reason: you didn’t analyze the workload.

CPU-bound and I/O-bound workloads behave very differently under concurrency.

“Fire and Forget” is a Production Bug

This is probably the most common concurrency bug

Go:

go processOrder(order)

Java:

executor.submit(() -> processOrder(order));

At firsst glance, this looks harmless.

In reality, you just lost:

• lifecycle control

• error handling

• cancellation

• ebservability

What happens in production:

• goroutines / threads keep running afrter the request is gone

• errors dissapear into logs (or nowhere)

• resource usage slowly climbs until something collapses

Rule of thumb: “If you start concurrent work, you must also define who owns it and who stops it”.

No Backpressure = Self-Inflicted DoS

Go:

for req := range requests {
    go handle(req)
}

Java:

requests.forEach(req ->
    executor.submit(() -> handle(req))
);

The bug:

• no limits

• no queue size

• no load scheduling

The result:

• traffic spike → thread explosion

• memory pressure

• GC storms (especially in Java)

• latency spikes everywhere

Backpressure is not an optimization. It’s a survival mechanism.

Backpressure in Go (conceptually):

workers := make(chan struct{}, 10)   // limit concurrency

func handle(req Request) {
    workers <- struct{}{}            // accuire slot
    defer func() { <-workers } ()    // release slot

    process(req)
}

If all slots are taken:

• the caller blocks

• work slows down naturally

• the system stays stable

The blocking is backpressure.

Backpressure in Java (conceptually):

ExecutorService executor = 
    new ThreadPoolExecutor(
        10, 10,
        0L, TimeUnit.MILLISECONDS,
        new ArrayBlockingQueue<>(100)
    );

Here:

• max 10 workers

• queue limited to 100 tasks

• when full → rejection policy kicks in

The rejection is backpressure.

Cancellation Is Treated as Optional (It’s Not)

Cancellation is one of those features everyone “supports” and almost no one uses correctly.

Go:

• context.Context passed around “just in case”

• nobody checks ctx.Done()

Java:

• InterruptedException ignored

• virtual threads assumed to auto-cancel everything

Why this hurts:

• request times out

• work continues anyway

• side effects happen after the client is gone

Cancellation must be:

• explicit

• propagated

• actively checked

If cancellation is an afterthought, your system will behave unpredictable under load.

Shared State: Different Tools, Same Pain

Go and Java take different approach here, but developers still manage to get it wrong.

Go:

• channels used as a magic solution

• mutexes added later, without clear ownership

Java:

• synchronized everywhere

• mutable shared objects crossing thread boundaries

The real problem: Not synchronization. Ownership.

If it’s unclear:

• who owns the data

• who is allowed to mutate it

• when it can be accessed

…then concurrency bugs are inevitable.

Prefer:

• immutable data

• clear boundaries

• single-writer patterns

Blocking Where It Hurst Most

Blocking is not evil. Blocking in the wrong place is.

Go:

• blocking I/O in unlimited goroutines

• time.Sleep used for coordination

Java:

• blocking calls inside virtual threads

• mixing async and blocking APIs blindly

Symptoms:

• thread pools stuck

• request queues growing

• sudden latency cliffs

Virtual threads reduce the cost of blocking, but they do not eliminate it.

Debugging Concurrency “By Logs”

Logs don’t explain concurrency issues. They only confirm that something already went wrong.

Common mistakes:

• no metrics

• no visibility into queues or workers

• debugging via stack traces only

What actually helps:

• Go: pprof, goroutine dumps

• Java: JFR, thread dumps

• metrics like:

  • queue depth

  • active workers

  • execution time distribution

If you can’t see concurrency behavior, you can’t fix it.

The Biggest Shared Mistake: Thinking Too Low-Level

Most concurrency bugs don’t come from goroutines or threads.

They come from thinking in terms of how work runs, instead of how work flows.

Stop designing systems around:

• goroutines

• threads

• and executors.

Start designing around:

• data flow

• limits

• ownership

• failure models

Design Over Language

Go and Java look very different on the surface.

But in production, concurrency failures usually come from the same place: design, not language.

• Go makes it easy to start concurrent work

• Java makes you think harder before you do

• neither will save you from bad assumptions

Concurrency is not a feature.

It’s a responsibility.

Cheers!

Sources

• Virtual Threads: https://docs.oracle.com/en/java/javase/21/core/virtual-threads.html

• Concurrency: https://docs.oracle.com/en/java/javase/21/core/concurrency.html

• No K.I.S.S.! samples for today ¯\_(ツ)_/¯

There’s a lot of teams that thinks about themselves as “agile”, they do have JIRA, they do the standups, but if we look closely at their release cycle it says otherwise.

They can plan sprints, push to main and then they… wait. They wait for the QA - a week. Then for the UAT testing phase - another week. Then for the Release Window.

By the time the feature hits production, everyone forgot why it was built.

Slow releases kill developer momentum and delay the only thing that matters - feedback from real users.

What RERO Really Means

RERO - Realease Early, Release Often - isn’t about deploying half-baked code. It’s abt shortening the feedback loop between code and reality.

• Release Early → push features to production as soon as they’re functional, not perfect

• Realease Often → make deployment a non-event; something you do daily, not quarterly (or monthly)

The goal isn’t speed for the sake of speed.

The goal is learning faster than your competition.

Why It Works

Every release is a feedback opportunity. EVery deployment tests your delivery pipeline, your observability, and your assumptions.

The more often you release:

• the smaller your changes are → they’re easier to debug (this is uber important part!)

• the faster you catch the regression (if any) → you lower the risk

• the quicker you learn what users actually want → profit (better ROI)

RERO shifts focus from “perfect features” to conrtinuos improvement.

How to Apply RERO in Practice

1. Define What “Release Ready” Means:

   • Agree as a team what “good enough for release” means

   • Use your Definition of Done as the gate - not “it feels ready” (lol):

     • code reviewed

     • tests passing (CI)

     • feature flag enabled

     • rollback plan ready

2. Use Feature Flags:

   • Don’t wait until a feature is “fully complete”

   • Wrap it in a flag and ship it dark:

     •   if feature.IsEnabled("new_flow") {
             newFlow();
         } else {
             oldFlow();
         }
       

3. Automate Everything:

   • if your deployment requires a 10-step manual guid, you’ll never release often

   • Automate GH Actions, GL CI or wahtever you’re using - the key is zero (or minimal) friction deploys

4. Release Small, Release Confident:

   • Trunk based development helps

   • No more long-lived branches that rot for weeks - merge daily

   • Small commits = fast reviews = fewer conflicts = faster learning

5. Monitor and Rollback

   • RERO without monitoring is chaos

   • Make sure you can:

     • detect failures quickly (metrics, logs, alerts)

     • rollback instantly (blue/green or versioned deploys)

Common Pitfalls and How To Avoid Them

1. “We’ll release when QA approves” → Integrate QA into the pipeline. Use automated regression tests.

2. “Our users can’t handle frequent updates” → Use progressive rollouts: 5%, 25%, 100% (canary releases)

3. “We’re afraid of breaking production” → Build trust in rollback and observability.

4. “We don’t have time for this” → You don’t have time not to. Every delay costs learning.

It’s not just about speed - it’s about smoother flow. Velocity isn’t measured by lines of code - it’s measured by how fast you learn and adapt.

Final Thoughts

“Release Early, Release Often” is more than a slogan - it’s a mindset shift. It replaces fear with feedback and perfectionism with progress.

The faster you ship, the faster you learn. The faster you learn, the better you build.

Cheers!

Sources

• RERO: https://en.wikipedia.org/wiki/Release_early,_release_often

• Trunk Based Development: https://trunkbaseddevelopment.com/

• B/G deployment: https://en.wikipedia.org/wiki/Blue%E2%80%93green_deployment

• Canary Release: https://martinfowler.com/bliki/CanaryRelease.html

Parallelism makes it faster. Concurrency makest it work.

• Parallelism is about using more cores to finish tasks sooner.

• Concurrency is about organizing your code so multiple things can happen - even if they don’t all run at the same time.

If you’ve ever built an API that juggles thousands of requests or a background worker that consumes messages non-stop, you’ve touched the concurrency. And if you’ve tried to squeeze evey ms out of CPU-bound code - that’s parallelism.

Quick Defs (Practical, Not Academic)

This always confuses a lot of engineers.

The simplest way to explain the difference is to imagine yourself writing both hands at once on a different pages - this is parallelism.

When you write only one hand and swap pages - this is a concurrency.

Easy, right?

• Parallelism = true simultaneity / executing multiple things physically at once

• Concurrency = multitasking / managing multiple things

What Actually Limits Us

• CPU cores → true parallel speedup

• Blocking I/O → here’s where the concurrency shines

• Context switching cost → too many “workers” means overhead

• Coordination cost → locks, queues, channels can bottleneck

Use Cases

Based on the typical workload usages:

• Thousands outbound HTTP calls:

  • We want high throughput, acceptable latency

  • Concurrency overlaps the waiting time on sockets

• Message consumers (Kafka, Rabbit):

  • We want steady throughput

  • Concurrency scale workers while controlling commit/ack operations

• CPU-bound (image resize, JSON schema validation or huge payloads):

  • We want raw parallel speedup

  • Concurrency alone won’t help, we need more cores

Misconceptions

Nine women won’t give a birth to a child in a month

• “More threads/goroutines → faster” - not if you’re CPU-bound or thrashing the scheduler

• “Async always beats sync” - async done poorly adds latency and complexity

• “Locks are bad, channels are good” - both are tools, use them wisely otherwise you end up with deadlock or stall

A Tiny Thought Experiment

We must call 1000 slow 3rd party APIs (avg 200 ms).

• Serial is about 200 s wall-clock

• Concurrent (well-tuned pool) is close to the slowest batch (~200 - 400 ms), plus overhead and rate-limits

The win comes from overlapping waits, not raw CPU.

Write for Concurrency, Optimize for Parallelism

It’s easy to mix’em up, but there’s the practical takeway:

• Concurrency is how you structure your program to handle multiple things at once

• Parallelism is how the hardware executes them faster

• You can have one w/o the other - and most of the time, you start with concurrency and earn parallelism later

When you write Go code, every go func() you spawn is a bet that your runtime will handle the juggling well.

When you write Java code, every thread pool or async executor is your manual way of telling the system how much to juggle.

But neither concurrency nor parallelism is a silver bullet. They won’t fix slow algo or bad I/O patterns - they’ll just help you manage how the slowness happens.

So, before adding more threads, goroutines, or async magic, ask one simple question:

Am I trying to make this faster, or just make it work better?

Knowing that difference is the real skill.

Cheers!

Next to it there’s a little bit more clever sibling - goimports. At first glance it’s doing the same, but in practice it’s saving you a lot of time and frustration.

gofmt - The Classic That Keeps Things Tidy

gofmt it’s an official Go tool for the code formatting according to the language’s standards.

There’s no configuration, there’s no Google or Uber style, there’s just a Go style.

# One file formatting
gofmt -w main.go

# Directory formatting (recursively)
gofmt -w .

The -w flag means that the file will be overwritten with the gofmt's version if its styling is different.

To see the list of files that do not follow fhe gofmt's formatting you use the -l flag:

gofmt -l .

goimports - Formatting + Imports Management

goimports is a tool from the golang.org/x/tools/cmd/goimports package that can do everything what gofmt does and as a bonus automatically manages package imports.

Command goimports updates your Go import lines, adding missing ones and removing unreferenced ones.

Source: https://pkg.go.dev/golang.org/x/tools/cmd/goimports

Installation:

go install golang.org/x/tools/cmd/goimports@latest

Usage:

# Same as in the gofmt -> overwrite files with formatted version
goimports -w .

# List files whose formatting differs from goimport's
goimports -l .

What’s the difference from gofmt?

• Will add the missing imports, f.e. if you used the fmt.Println but forgot to import the fmt package

• Will remove the unused imports automatically

Example:

Before:

package main

import (
    "fmt"
    "os"
)

func main() {
    fmt.Println("Keep Is Simple, Stupid!")
}

After:

package main

import "fmt"

func main() {
    fmt.Println("Keep Is Simple, Stupid!")
}

How to Use Them on a Daily Basis

The best tool is a one that you don’t have to remember about.

You can set up them in the IDE or CI, so they’re executed automatically.

My JetBrains GoLand’s code style is as follows:

For the VS Code it should look like this:

The settings.json file:

{
  "go.formatTool": "goimports",
  "editor.formatOnSave": true
}

For the GitHub’s CI / GitHub Actions:

- name: Install goimports
  run: go install golang.org/x/tools/cmd/goimports@latest
- name: Verify formatting & imports
  run: test -z "$(goimports -l .)"

If you have to choose one, use goimports. It's like gofmt on steroids, and it also saves you a few seconds per file.

Finally, Keep It Simple, Stupid!

Sources

• gofmt: https://pkg.go.dev/cmd/gofmt

• goimports: https://pkg.go.dev/golang.org/x/tools/cmd/goimports

• Go tools: https://cs.opensource.google/go/x/tools

• go fmt your code: https://go.dev/blog/gofmt

• The Go Programming Language: https://cs.opensource.google/go/go

The MCP tool will be working in the STDIO mode and can be added to any other LLM tool that is supporting the MCP standard. We’re going to use the Goland as an example.

What is the Model Context Protocol (MCP)

The Model Context Protocol (MCP) is an open standard, open-source framework introduced by Anthropic in November 2024 to standardize the way artificial intelligence (AI) systems like large language models (LLMs) integrate and share data with external tools, systems, and data sources.^[1] MCP provides a universal interface for reading files, executing functions, and handling contextual prompts.^[2] Following its announcement, the protocol was adopted by major AI providers, including OpenAI and Google DeepMind.^[3][4]

Source: https://en.wikipedia.org/wiki/Model_Context_Protocol

In other other words, it’s a “common language” that let’s AI models talk to tools, data and apps.

Building the MCP Server

For this article I’m going to use the community library mark3labs/mcp-go that fully supports the MCP standard.

You have to be aware there’s also an official Go SDK for the MCP which is less stable, but provides more strict approach, however requires more bolierplate to kickstart the project.

Okay, straight to the point.

Let’s install the package:

go get github.com/mark3labs/mcp-go

And head straight to setting up the MCP server:

s := server.NewMCPServer(
        "Wikipedia Search",
        "v1.0.0",
        server.WithToolCapabilities(false),
        server.WithRecovery(),
    )

Then the tool definition. This is the part that is being exposed as an “interface” to the “model” client:

wikiTool := mcp.NewTool(
        "wikipedia_search",
        mcp.WithDescription("Search Wikipedia for a query and return the first paragraph"),
        mcp.WithString("query", mcp.Required(), mcp.Description("Search term")),
    )

Now, let’s connect the server and the tool definition:

s.AddTool(wikiTool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        term, err := req.RequireString("query")
        if err != nil {
            return nil, fmt.Errorf("failed to get query: %w", err)
        }

        u := fmt.Sprintf("https://en.wikipedia.org/api/rest_v1/page/summary/%s", url.PathEscape(term))

        ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
        defer cancel()

        httpReq, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
        if err != nil {
            return nil, fmt.Errorf("failed to create request: %w", err)
        }
        httpReq.Header.Set("User-Agent", "Wikipedia-MCP-Server/1.0")

        r, err := http.DefaultClient.Do(httpReq)
        if err != nil {
            return nil, fmt.Errorf("failed to get wikipedia page: %w", err)
        }
        defer func() {
            if closeErr := r.Body.Close(); closeErr != nil {
                fmt.Printf("Warning: failed to close response body: %v\n", closeErr)
            }
        }()

        if r.StatusCode != http.StatusOK {
            return nil, fmt.Errorf("failed to get wikipedia page: %s", r.Status)
        }

        body, err := io.ReadAll(io.LimitReader(r.Body, 1024*1024))
        if err != nil {
            return nil, fmt.Errorf("failed to read response body: %w", err)
        }

        var summary struct {
            Extract string `json:"extract"`
        }
        if err := json.Unmarshal(body, &summary); err != nil {
            return nil, fmt.Errorf("failed to parse response: %w", err)
        }

        if summary.Extract == "" {
            return nil, fmt.Errorf("no summary found for '%s'", term)
        }

        return mcp.NewToolResultText(summary.Extract), nil
    })

Our tool is calling the Wiki API and parsing the summary for the given query. It’s limited to process only 1MB of data and has a timeout of 10 seconds, to not get locked if the network issues will occur.

The last thing required is to run the MCP server:

if err := server.ServeStdio(s); err != nil {
        fmt.Printf("Server error: %v\n", err)
    }

Compiling the MCP Server

To build a real binary application, that can be run in the background an serve as an MCP server, you need to:

go build -o mcp-wiki-tool

And that’s it. When the model will need it it will run it by itself.

Connecting to Amazon Q

In your JetBrains IDE, open Amazon Q plugin and select the followings:

1. Configure MCP servers:

2. Add new MCP server:

3. Provide the details about our newly created MCP server:

Click “Save” and you’re good to go.

On your MCP servers list you should see “WikipediaSearch”:

Now, anytime you ask anything related to the Wikipedia or Amazon Q decides it needs a data from the Wikipedia it will use your model.

You can configure the Amazon Q how it should behave when using your new tool:

You can approve the usage of the tool each time the Amazon Q needs it or just allow it to be used in the background seamlessly.

Our MCP server in action:

Expanding with More Useful Tools

As you can see, the capabilities of the MCP servers are limitless. You can expand your model’s context in a way you want and access tools that aren’t publicly available on the internet.

The MCP is for the models the same what the HTTP was for the Internet. It standardizes the information exchange format.

Please keep in mind that MCP servers are not only for the read-only mode. You can expose endpoints that will be modyfing state of your application, like “attlasian” MCP server allows to manage Jira on your behalf, manage tickets, stories and everything related.

Sources

As always the full source code used for this article you can find on my GitHub: https://github.com/flashlabs/kiss-samples/tree/main/mcp

• MCP GO SDK: https://github.com/mark3labs/mcp-go

• Official MCP GO SDK: https://github.com/modelcontextprotocol/go-sdk

• MCP Wiki: https://en.wikipedia.org/wiki/Model_Context_Protocol

• MCP Official Website: https://modelcontextprotocol.io/

• MCP Official GH: https://github.com/modelcontextprotocol

• Article’s Golang Repository: https://github.com/flashlabs/kiss-samples/tree/main/mcp

Notes:

• the inference example is based on the yalue examples

• the code used in this article is adapted to the MacOS with the ARM architecture, for other OSes and architecures, you will need libs available here and an example on how to use them is located here

Step 1: Convert YOLO to ONNX

First we need to convert the YOLOv8 model to the ONNX format. To do this we’ll install the ultralytics package with pip and use the yolo export command.

The image size here - 640 - is important, it has to be the same size that we’ll use later in our code.

mkdir yolov8 && cd yolov8

# Create and enable virtual env.
python3.10 -m venv env
source env/bin/activate

pip install ultralytics

yolo export model=yolov8n.pt format=onnx imgsz=640

# Quit virtual env.
deactivate

The ouput should be similar to:

(...)
ONNX: starting export with onnx 1.17.0 opset 17...
ONNX: slimming with onnxslim 0.1.61...
ONNX: export success ✅ 19.8s, saved as 'yolov8n.onnx' (12.2 MB)

Export complete (20.5s)
Results saved to /(...)/yolov8
Predict:         yolo predict task=detect model=yolov8n.onnx imgsz=640  
Validate:        yolo val task=detect model=yolov8n.onnx imgsz=640 data=coco.yaml  
Visualize:       https://netron.app
💡 Learn more at https://docs.ultralytics.com/modes/export

This will create a yolov8n.onnx file with the onnx YOLOv8 model. Please be sure to copy the model to your directory.

I’ve already included a converted model file in the article full code example.

Step 2: Load Image File

pic, e := loadImageFile(imagePath)
if e != nil {
    fmt.Printf("error loading input image: %s\n", e)

    return 1
}

(...)

func loadImageFile(filePath string) (image.Image, error) {
    f, e := os.Open(filePath)

    if e != nil {
        return nil, fmt.Errorf("error opening %s: %w", filePath, e)
    }
    defer func(f *os.File) {
        err := f.Close()
        if err != nil {
            fmt.Printf("error closing %s: %v\n", filePath, err)
        }
    }(f)

    pic, _, e := image.Decode(f)
    if e != nil {
        return nil, fmt.Errorf("error decoding %s: %w", filePath, e)
    }

    return pic, nil
}

Step 3: Init ONNX Session

modelSession, e := initSession()
if e != nil {
    fmt.Printf("Error creating session and tensors: %s\n", e)

    return 1
}
defer modelSession.Destroy()

(...)

func initSession() (*ModelSession, error) {
    ort.SetSharedLibraryPath(sharedLibPath)

    err := ort.InitializeEnvironment()
    if err != nil {
        return nil, fmt.Errorf("error initializing ORT environment: %w", err)
    }

    inputShape := ort.NewShape(1, 3, 640, 640)

    inputTensor, err := ort.NewEmptyTensor[float32](inputShape)
    if err != nil {
        return nil, fmt.Errorf("error creating input tensor: %w", err)
    }

    outputShape := ort.NewShape(1, 84, 8400)

    outputTensor, err := ort.NewEmptyTensor[float32](outputShape)
    if err != nil {
        inputTensor.Destroy()
        return nil, fmt.Errorf("error creating output tensor: %w", err)
    }

    options, err := ort.NewSessionOptions()
    if err != nil {
        inputTensor.Destroy()
        outputTensor.Destroy()
        return nil, fmt.Errorf("error creating ORT session options: %w", err)
    }
    defer options.Destroy()

    session, err := ort.NewAdvancedSession(modelPath,
        []string{"images"}, []string{"output0"},
        []ort.ArbitraryTensor{inputTensor},
        []ort.ArbitraryTensor{outputTensor},
        options)
    if err != nil {
        inputTensor.Destroy()
        outputTensor.Destroy()
        return nil, fmt.Errorf("error creating ORT session: %w", err)
    }

    return &ModelSession{
        Session: session,
        Input:   inputTensor,
        Output:  outputTensor,
    }, nil
}

Step 4: Prepare Input

This is where we need to use the data from the image and fill the YOLO input tensor with it:

e = prepareInput(pic, modelSession.Input)
if e != nil {
    fmt.Printf("Error converting image to network input: %s\n", e)

    return 1
}

(...)

// Populates a YOLOv8n input tensor with the contents of the given image.
func prepareInput(pic image.Image, dst *ort.Tensor[float32]) error {
    data := dst.GetData()
    channelSize := 640 * 640
    if len(data) < (channelSize * 3) {
        return fmt.Errorf("destination tensor only holds %d floats, needs %d (make sure it's the right shape!)", len(data), channelSize*3)
    }
    redChannel := data[0:channelSize]
    greenChannel := data[channelSize : channelSize*2]
    blueChannel := data[channelSize*2 : channelSize*3]

    // Resize the image to 640x640 using Lanczos3 algorithm
    pic = resize.Resize(640, 640, pic, resize.Lanczos3)
    i := 0
    for y := 0; y < 640; y++ {
        for x := 0; x < 640; x++ {
            r, g, b, _ := pic.At(x, y).RGBA()
            redChannel[i] = float32(r>>8) / 255.0
            greenChannel[i] = float32(g>>8) / 255.0
            blueChannel[i] = float32(b>>8) / 255.0
            i++
        }
    }

    return nil
}

Step 5: Run Session

Run the inference:

e = modelSession.Session.Run()
if e != nil {
    fmt.Printf("Error running ORT session: %s\n", e)

    return 1
}

Step 6: Process Output

Now we need to process the inference results and prepare an output in a human readable format:

boxes := processOutput(modelSession.Output.GetData(), originalWidth,
        originalHeight)
for i, box := range boxes {
    fmt.Printf("Box %d: %s\n", i, &box)
}

(...)

func processOutput(output []float32, originalWidth,
    originalHeight int) []boundingBox {
    boundingBoxes := make([]boundingBox, 0, 8400)

    var classID int
    var probability float32

    // Iterate through the output array, considering 8400 indices
    for idx := 0; idx < 8400; idx++ {
        // Iterate through 80 classes and find the class with the highest probability
        probability = -1e9
        for col := 0; col < 80; col++ {
            currentProb := output[8400*(col+4)+idx]
            if currentProb > probability {
                probability = currentProb
                classID = col
            }
        }

        // If the probability is less than 0.5, continue to the next index
        if probability < 0.5 {
            continue
        }

        // Extract the coordinates and dimensions of the bounding box
        xc, yc := output[idx], output[8400+idx]
        w, h := output[2*8400+idx], output[3*8400+idx]
        x1 := (xc - w/2) / 640 * float32(originalWidth)
        y1 := (yc - h/2) / 640 * float32(originalHeight)
        x2 := (xc + w/2) / 640 * float32(originalWidth)
        y2 := (yc + h/2) / 640 * float32(originalHeight)

        // Append the bounding box to the result
        boundingBoxes = append(boundingBoxes, boundingBox{
            label:      yoloClasses[classID],
            confidence: probability,
            x1:         x1,
            y1:         y1,
            x2:         x2,
            y2:         y2,
        })
    }

    // Sort the bounding boxes by probability
    sort.Slice(boundingBoxes, func(i, j int) bool {
        return boundingBoxes[i].confidence < boundingBoxes[j].confidence
    })

    // Define a slice to hold the final result
    mergedResults := make([]boundingBox, 0, len(boundingBoxes))

    // Iterate through sorted bounding boxes, removing overlaps
    for _, candidateBox := range boundingBoxes {
        overlapsExistingBox := false
        for _, existingBox := range mergedResults {
            if (&candidateBox).iou(&existingBox) > 0.7 {
                overlapsExistingBox = true
                break
            }
        }
        if !overlapsExistingBox {
            mergedResults = append(mergedResults, candidateBox)
        }
    }

    // This will still be in sorted order by confidence
    return mergedResults
}

It will produce something similar:

go run main.go
Box 0: Object laptop (confidence 0.524439): (213.599579, 243.196198), (419.911469, 350.581512)
Box 1: Object cup (confidence 0.563491): (433.477356, 257.403839), (571.929077, 355.463074)
Box 2: Object parking meter (confidence 0.578624): (406.172058, 50.842918), (565.424744, 231.428116)

The inference on the Apple M1 Pro (2020) takes about 10 seconds.

Step 7: Draw Output Image with Boxes

In this step we create an output image based on the input image, but with the boxes marking detected objects.

Note:

• for labels you need to provide the correct path to the font you want to use (see fontPath const at the top of the program)

const (
    outputImagePath = "./output.jpg"
(...)
    fontPath        = "/Library/Fonts/Arial Unicode.ttf"
)

(...)

err := drawBoxes(imagePath, outputImagePath, boxes)
if err != nil {
    fmt.Printf("error drawing boxes: %s\n", err)

    return 1
}

(...)

// Draws bounding boxes with labels onto the image and saves the result
func drawBoxes(inputPath string, outputPath string, boxes []boundingBox) error {
    // Open and decode the image
    f, err := os.Open(inputPath)
    if err != nil {
        return fmt.Errorf("error opening input image: %w", err)
    }
    defer f.Close()

    img, _, err := image.Decode(f)
    if err != nil {
        return fmt.Errorf("error decoding image: %w", err)
    }

    dc := gg.NewContextForImage(img)
    dc.SetLineWidth(1)
    fontLoaded := false
    if err := dc.LoadFontFace(fontPath, 14); err == nil {
        fontLoaded = true
    }

    for _, box := range boxes {
        // Draw rectangle
        dc.SetRGB(1, 0, 0) // red
        dc.DrawRectangle(float64(box.x1), float64(box.y1), float64(box.x2-box.x1), float64(box.y2-box.y1))
        dc.Stroke()

        // Draw label
        if fontLoaded {
            label := fmt.Sprintf("%s (%.2f)", box.label, box.confidence)
            dc.SetRGB(0, 0, 1)
            dc.DrawStringAnchored(label, float64(box.x1)+4, float64(box.y1)-4, 0, 1)
        }
    }

    // Save the result
    out, err := os.Create(outputPath)
    if err != nil {
        return fmt.Errorf("error creating output file: %w", err)
    }
    defer out.Close()

    return jpeg.Encode(out, dc.Image(), &jpeg.Options{Quality: 90})
}

The output should be like this:

Hope you like it! Nice hacking!

Sources

• ONNX Runtime: https://github.com/yalue/onnxruntime_go

• Image detection: https://github.com/yalue/onnxruntime_go_examples/tree/master/image_object_detect

• Sample images: https://www.kaggle.com/datasets/kkhandekar/object-detection-sample-images

• Virtual envs: https://docs.python.org/3/library/venv.html

• Article Golang code repository: https://github.com/flashlabs/kiss-samples/tree/main/yolo-in-go-with-onnx

• Call a YOLO model via the Python REST API

• Communicate via the gRPC with Python service that runs a YOLO model

• Use the onnxruntime_go to run the YOLO model in native GO environment

Today we’re going to focus on the fastest approach of all three of them, which is calling a YOLO model via the Python REST API.

Architecture

We’re going to write a simple Golang application, that will call the Python REST API with the provided image and write the model inference results to the CLI.

Golang ⇄ HTTP ⇄ Python (YOLOv5 inference)

With this approach, we’re getting:

• Minimal setup

• Quite nice performance, since it’s the Python that is doing the heavy lifting (YOLO inference)

• Easy to containerize (two separate services: Go + Python)

Project structure:

yolo-in-go-with-python/
├── go-backend/
│   ├── go.mod
│   └── main.go
├── yolo-api/
│   ├── detect.py
│   └── requirements.txt
└── example.jpg

Looks simple, right? It is!

Python Inference Server (YOLOv5)

A minimal FastAPI server:

from fastapi import FastAPI, File, UploadFile
from fastapi.responses import JSONResponse
import torch
from PIL import Image
import io

# Initialize the FastAPI application
app = FastAPI()
# Load the pretrained YOLOv5s model from the Ultralytics repository
model = torch.hub.load("ultralytics/yolov5", "yolov5s", pretrained=True)

# Define the endpoint to handle object detection requests
@app.post("/detect")
async def detect(file: UploadFile = File(...)):
    # Read the uploaded image file as bytes
    image_bytes = await file.read()
    # Convert the byte data to a PIL Image
    image = Image.open(io.BytesIO(image_bytes))
    # Run the image through the YOLO model
    results = model(image)
    # Convert the detection results to a JSON response
    return JSONResponse(results.pandas().xyxy[0].to_dict(orient="records"))

Requirements:

The base server reqs are:

torch
fastapi
uvicorn
pillow

but in the requirements.txt you can find all my deps freeze that was used during this tutorial.

I strongly recommend using the venv - https://docs.python.org/3/library/venv.html and not to install the reqs in your local environment.

1. Install deps: pip install -r requirements.txt

2. Start a server: uvicorn detect:app --host 0.0.0.0 --port 8000

You should see something like this:

uvicorn detect:app --host 0.0.0.0 --port 8000
Using cache found in /.../.cache/torch/hub/ultralytics_yolov5_master
/.../.cache/torch/hub/ultralytics_yolov5_master/utils/general.py:32: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.
  import pkg_resources as pkg
YOLOv5 🚀 2025-6-29 Python-3.11.6 torch-2.2.2 CPU

Fusing layers... 
[W NNPACK.cpp:64] Could not initialize NNPACK! Reason: Unsupported hardware.
YOLOv5s summary: 213 layers, 7225885 parameters, 0 gradients, 16.4 GFLOPs
Adding AutoShape... 
INFO:     Started server process [28206]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Don’t mind the NNPACK warning, it’s related to the optimization that couldn’t be applied. All is working correctly!

Go Client to Call YOLOv5

Go Client:

package main

import (
    "bytes"
    "fmt"
    "io"
    "log"
    "mime/multipart"
    "net/http"
    "os"
    "path/filepath"
)

const (
    filePath   = "../example.jpg"
    yoloAPIURL = "http://localhost:8000/detect"
)

// main is the entry point for the application. It prepares the image,
// sends it to the YOLO API, and prints the result.
func main() {
    // Prepare the image file as a multipart form
    body, contentType, err := prepareMultipartForm(filePath)
    if err != nil {
        log.Fatal("Error preparing multipart form: ", err)
    }

    // Send the HTTP POST request to the YOLO API
    respBytes, err := sendYOLORequest(yoloAPIURL, body, contentType)
    if err != nil {
        log.Fatal("Error sending YOLO request: ", err)
    }

    // Print the detection results
    fmt.Println(string(respBytes))
}

// prepareMultipartForm creates a multipart/form-data body from the given file path.
// It returns the form body, content type, and any error encountered.
func prepareMultipartForm(filePath string) (*bytes.Buffer, string, error) {
    body := &bytes.Buffer{}
    writer := multipart.NewWriter(body)

    // Open the file
    file, err := os.Open(filePath)
    if err != nil {
        return nil, "", fmt.Errorf("failed to open file: %w", err)
    }
    defer func() {
        if e := file.Close(); e != nil {
            log.Println("Failed to close file", e)
        }
    }()

    // Create a new form file field
    part, err := writer.CreateFormFile("file", filepath.Base(filePath))
    if err != nil {
        return nil, "", fmt.Errorf("failed to create form file: %w", err)
    }

    // Copy the image data into the form
    _, err = io.Copy(part, file)
    if err != nil {
        return nil, "", fmt.Errorf("failed to copy file: %w", err)
    }

    // Close the multipart writer
    if err = writer.Close(); err != nil {
        log.Println("Failed to close writer", err)
    }

    return body, writer.FormDataContentType(), nil
}

// sendYOLORequest sends the image as a multipart POST request to the specified YOLO API.
// It returns the response body or an error.
func sendYOLORequest(apiURL string, body *bytes.Buffer, contentType string) ([]byte, error) {
    // Create a new HTTP POST request with the multipart data
    req, err := http.NewRequest(http.MethodPost, apiURL, body)
    if err != nil {
        return nil, fmt.Errorf("failed to create request: %w", err)
    }
    req.Header.Set("Content-Type", contentType)

    // Send the request and get the response
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, fmt.Errorf("failed to execute request: %w", err)
    }
    defer func() {
        if e := resp.Body.Close(); e != nil {
            log.Println("Failed to close body", e)
        }
    }()

    // Read and return the response body
    respBytes, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, fmt.Errorf("failed to read response body: %w", err)
    }

    return respBytes, nil
}

Run the Inference

1. The Python REST API is up & running, if not, execute:

cd yolo-api && uvicorn detect:app --host 0.0.0.0 --port 8000

2. Run the Go app:

cd go-backend && go run main.go

You should see the output like this:

go run main.go
[{"xmin":451.77557373046875,"ymin":256.8055114746094,"xmax":572.8908081054688,"ymax":355.9529724121094,"confidence":0.8660547733306885,"class":41,"name":"cup"},{"xmin":216.73318481445312,"ymin":242.79660034179688,"xmax":417.9637756347656,"ymax":352.3187561035156,"confidence":0.3558332026004791,"class":67,"name":"cell phone"},{"xmin":0.4250640869140625,"ymin":0.6914291381835938,"xmax":276.78839111328125,"ymax":174.0032958984375,"confidence":0.27563828229904175,"class":73,"name":"book"},{"xmin":211.1724090576172,"ymin":242.36141967773438,"xmax":421.87457275390625,"ymax":351.2012634277344,"confidence":0.26584678888320923,"class":63,"name":"laptop"}]

With the “pretty print” it loos like this:

go run main.go | jq .
[
  {
    "xmin": 451.77557373046875,
    "ymin": 256.8055114746094,
    "xmax": 572.8908081054688,
    "ymax": 355.9529724121094,
    "confidence": 0.8660547733306885,
    "class": 41,
    "name": "cup"
  },
  {
    "xmin": 216.73318481445312,
    "ymin": 242.79660034179688,
    "xmax": 417.9637756347656,
    "ymax": 352.3187561035156,
    "confidence": 0.3558332026004791,
    "class": 67,
    "name": "cell phone"
  },
  {
    "xmin": 0.4250640869140625,
    "ymin": 0.6914291381835938,
    "xmax": 276.78839111328125,
    "ymax": 174.0032958984375,
    "confidence": 0.27563828229904175,
    "class": 73,
    "name": "book"
  },
  {
    "xmin": 211.1724090576172,
    "ymin": 242.36141967773438,
    "xmax": 421.87457275390625,
    "ymax": 351.2012634277344,
    "confidence": 0.26584678888320923,
    "class": 63,
    "name": "laptop"
  }
]

As you can see this is mostly what we have in our image:

There’s no “laptop”, but the confidence score was really low - 0.26, so we shouldn’t be surprised by that. Also the “cell phone” is probably a tablet.

At the same time, your CLI output for the Python REST API show you incoming requests:

uvicorn detect:app --host 0.0.0.0 --port 8000
Using cache found in /.../.cache/torch/hub/ultralytics_yolov5_master
/.../.cache/torch/hub/ultralytics_yolov5_master/utils/general.py:32: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.
  import pkg_resources as pkg
YOLOv5 🚀 2025-6-29 Python-3.11.6 torch-2.2.2 CPU

Fusing layers... 
[W NNPACK.cpp:64] Could not initialize NNPACK! Reason: Unsupported hardware.
YOLOv5s summary: 213 layers, 7225885 parameters, 0 gradients, 16.4 GFLOPs
Adding AutoShape... 
INFO:     Started server process [28206]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     127.0.0.1:51144 - "POST /detect HTTP/1.1" 200 OK
INFO:     127.0.0.1:51146 - "POST /detect HTTP/1.1" 200 OK
INFO:     127.0.0.1:51147 - "POST /detect HTTP/1.1" 200 OK
INFO:     127.0.0.1:51150 - "POST /detect HTTP/1.1" 200 OK

Have fun with detections!

Sources

• Article Golang code repository: https://github.com/flashlabs/kiss-samples/tree/main/yolo-in-go-with-python

• Sample images: https://www.kaggle.com/datasets/kkhandekar/object-detection-sample-images

• Virtual Environment: https://docs.python.org/3/library/venv.html

As a base we’ll use the code from the previous article “Running TensorFlow Models in Golang” and work on that.

We’ll do a little bit of refactoring regarding the architecture and introduce the modular folder structure for the easier maintenance and scalability.

Note: for setting up the environment and preparing the model please take a look at Setting Up the Environment section of the previous article.

Architecture

We’re going to split the logic that was previously in the main.go file into smaller chunks:

.
├── main.go                          # entry point
├── internal/
│   ├── inference/
│   │   ├── model.go                 # model loading + prediction
│   │   └── labels.go                # label loading
│   └── handler/
│       └── predict.go               # HTTP handler
├── model/
│   └── mobilenet_v2/                # saved_model.pb + variables/
├── static/
│   └── example.jpg
├── ImageNetLabels.txt
├── go.mod
└── go.sum

Model

Loading a model to the memory in model.go file in the inference package and exposing it via the public Model variable:

package inference

import (
    "fmt"

    tf "github.com/wamuir/graft/tensorflow"
)

var Model *tf.SavedModel

func LoadModel(path string) (err error) {
    Model, err = tf.LoadSavedModel(path, []string{"serve"}, nil)
    if err != nil {
        return fmt.Errorf("LoadSavedModel: %w", err)
    }

    return nil
}

Labels

Loading labels into the Labels public variable in the labels.go file in the inference package:

package inference

import (
    "bufio"
    "fmt"
    "log"
    "os"
)

var Labels []string

func LoadLabels(path string) error {
    file, err := os.Open(path)
    if err != nil {
        return fmt.Errorf("os.Open: %w", err)
    }

    defer func(file *os.File) {
        if e := file.Close(); e != nil {
            log.Println("file.Close", e)
        }
    }(file)

    var labels []string

    scanner := bufio.NewScanner(file)
    for scanner.Scan() {
        labels = append(labels, scanner.Text())
    }

    if err = scanner.Err(); err != nil {
        return fmt.Errorf("bufio.Scanner: %w", err)
    }

    Labels = labels

    return nil
}

Note that the contents of the Labels var we’re updating only when the whole process has completed successfully.

Handler

The main logic from our previous article we need to move to the http server handler - the Predict in this example.

The makeTensorFromImage helper function comes here with us.

package handler

import (
    "fmt"
    "image"
    "image/jpeg"
    "log"
    "mime/multipart"
    "net/http"

    "github.com/nfnt/resize"
    tf "github.com/wamuir/graft/tensorflow"

    "github.com/flashlabs/kiss-samples/tensorflowrestapi/internal/inference"
)

func Predict(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodPost {
        http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)

        return
    }

    file, _, err := r.FormFile("image")
    if err != nil {
        http.Error(w, "Failed to get images", http.StatusBadRequest)

        return
    }
    defer func(file multipart.File) {
        if e := file.Close(); e != nil {
            log.Println("file.Close", e)
        }
    }(file)

    img, err := jpeg.Decode(file)
    if err != nil {
        http.Error(w, "Failed to decode image", http.StatusBadRequest)

        return
    }

    tensor, err := makeTensorFromImage(img)
    if err != nil {
        http.Error(w, "Failed to make tensor from image", http.StatusInternalServerError)

        return
    }

    input := inference.Model.Graph.Operation("serving_default_x")
    output := inference.Model.Graph.Operation("StatefulPartitionedCall")

    outputs, err := inference.Model.Session.Run(
        map[tf.Output]*tf.Tensor{
            input.Output(0): tensor,
        },
        []tf.Output{
            output.Output(0),
        },
        nil,
    )
    if err != nil {
        http.Error(w, "Failed to run inference", http.StatusInternalServerError)

        return
    }

    predictions := outputs[0].Value().([][]float32)

    bestIdx, bestScore := 0, float32(0.0)
    for i, p := range predictions[0] {
        if p > bestScore {
            bestIdx, bestScore = i, p
        }
    }

    label := inference.Labels[bestIdx]

    _, err = fmt.Fprintf(w, `{"class_id": %d, "label": "%s", "confidence": %.4f}`+"\n", bestIdx, label, bestScore)
    if err != nil {
        http.Error(w, "Failed to write response", http.StatusInternalServerError)

        return
    }
}

func makeTensorFromImage(img image.Image) (*tf.Tensor, error) {
    // Resize to 224x224
    resized := resize.Resize(224, 224, img, resize.Bilinear)

    // Create a 4D array to hold input
    bounds := resized.Bounds()
    batch := make([][][][]float32, 1) // batch size 1
    batch[0] = make([][][]float32, bounds.Dy())

    for y := bounds.Min.Y; y < bounds.Max.Y; y++ {
        row := make([][]float32, bounds.Dx())
        for x := bounds.Min.X; x < bounds.Max.X; x++ {
            r, g, b, _ := resized.At(x, y).RGBA()
            row[x] = []float32{
                float32(r) / 65535.0, // normalize to [0,1]
                float32(g) / 65535.0,
                float32(b) / 65535.0,
            }
        }
        batch[0][y] = row
    }

    return tf.NewTensor(batch)
}

Please note that instead of logging fatals, we need to write an output to the http.ResponeWriter and break the processing, so the client side knows what’s wrong with the request processing, f.e. if the request method is not POST, we need to communicate this issue with the proper message and the HTTP status code:

if r.Method != http.MethodPost {
    http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)

    return
}

Main Program

Now, having all the logic extracted into the proper packages our main program looks like it should looks like - it’s small and compatc and is responsible for initialization and running the main process:

package main

import (
    "fmt"
    "log"
    "net/http"

    "github.com/flashlabs/kiss-samples/tensorflowrestapi/internal/handler"
    "github.com/flashlabs/kiss-samples/tensorflowrestapi/internal/inference"
)

func main() {
    fmt.Println("Loading TF model...")
    if err := inference.LoadModel("model/saved_mobilenet_v2"); err != nil {
        log.Fatalf("Failed to load SavedModel: %v", err)
    }

    fmt.Println("Loading labels...")
    if err := inference.LoadLabels("ImageNetLabels.txt"); err != nil {
        log.Fatalf("Failed to load labels: %v", err)
    }

    fmt.Println("Setting up handlers...")
    http.HandleFunc("/predict", handler.Predict)

    fmt.Println("listening on :8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

As you can see all it does is:

• Loading a TF model

• Loading labels

• Setting up the HTTP handlers

• Starting a HTTP server on the local port 8080

Running a Program

Just run main.go with the go run main.go and expect the output similar to this:

go run main.go
Loading TF model...
2025-05-18 13:29:22.879008: I tensorflow/cc/saved_model/reader.cc:83] Reading SavedModel from: model/saved_mobilenet_v2
2025-05-18 13:29:22.886212: I tensorflow/cc/saved_model/reader.cc:52] Reading meta graph with tags { serve }
2025-05-18 13:29:22.886235: I tensorflow/cc/saved_model/reader.cc:147] Reading SavedModel debug info (if present) from: model/saved_mobilenet_v2
WARNING: All log messages before absl::InitializeLog() is called are written to STDERR
I0000 00:00:1747567762.933428 11558409 mlir_graph_optimization_pass.cc:425] MLIR V1 optimization pass is not enabled
2025-05-18 13:29:22.940719: I tensorflow/cc/saved_model/loader.cc:236] Restoring SavedModel bundle.
2025-05-18 13:29:23.159484: I tensorflow/cc/saved_model/loader.cc:220] Running initialization op on SavedModel bundle at path: model/saved_mobilenet_v2
2025-05-18 13:29:23.217182: I tensorflow/cc/saved_model/loader.cc:471] SavedModel load for tags { serve }; Status: success: OK. Took 338178 microseconds.
Loading labels...
Setting up handlers...
listening on :8080

Making a REST Call

Be sure to be in the project directory to be able to read the static/example.jpg file:

curl -X POST -F image=@static/example.jpg http://localhost:8080/predict
{"class_id": 469, "label": "cab", "confidence": 12.6021}

Looking at our example.jpg file:

We can see it’s working.

Next Steps

You have a fully working example of a REST API that handles a POST requests with image payloads.

You might want to add more endpoints, validation, detect image sizes and so on.

The sky is the limit.

Sources

• Article Golang code repository: https://github.com/flashlabs/kiss-samples/tree/main/tensorflowrestapi

• Sample images: https://www.kaggle.com/datasets/kkhandekar/object-detection-sample-images

• ImageNet labels: https://storage.googleapis.com/download.tensorflow.org/data/ImageNetLabels.txt

Now, because of the

The TensorFlow team is not currently maintaining the Documentation for installing the Go bindings for TensorFlow.

https://github.com/tensorflow/tensorflow/tree/master/tensorflow/go

The new “official” contributor for the Go bindings (as recommended by the TF itself) is William Muir and his graft repo - https://github.com/wamuir/graft

Setting Up the Environment

Reqs:

• Go 1.21+

• TensorFlow (TF) installed (Go bindings rely on TF C library)

Installing the TF:

brew install tensorflow

Installing the Go TF package:

go get -u github.com/wamuir/graft/tensorflow/...

To check if your TF installation works, please follow the “Hello Tensorflow” example from the graft README - https://github.com/wamuir/graft:

package main

import (
    tf "github.com/wamuir/graft/tensorflow"
    "github.com/wamuir/graft/tensorflow/op"
    "fmt"
)

func main() {
    // Construct a graph with an operation that produces a string constant.
    s := op.NewScope()
    c := op.Const(s, "Hello from TensorFlow version " + tf.Version())
    graph, err := s.Finalize()
    if err != nil {
        panic(err)
    }

    // Execute the graph in a session.
    sess, err := tf.NewSession(graph, nil)
    if err != nil {
        panic(err)
    }
    output, err := sess.Run(nil, []tf.Output{c}, nil)
    if err != nil {
        panic(err)
    }
    fmt.Println(output[0].Value())
}

The output when you run the program should be similar to this one:

go run main.go
WARNING: All log messages before absl::InitializeLog() is called are written to STDERR
I0000 00:00:1745750228.799498 1712814 mlir_graph_optimization_pass.cc:425] MLIR V1 optimization pass is not enabled
Hello from TF version 2.19.0

In case of any issues please refer to the section “Common Pitfalls and Troubleshooting” at the end of this article.

Preparing the Model

We’re going to use the pre-trained image classifier model mobilenet_v2 - https://www.kaggle.com/models/google/mobilenet-v2/tensorFlow2

Unfortunately the model downloaded from the given source had issues with the provided input layer, so in the blog article repository (see “Sources”) you can find a converter.py script, that exported it from source and provided us with the named input layer called serving_default_x.

You don’t have to do it, it’s already done, but you can take a look at the converter.py to see how you can export a model to a SavedModel format.

Loading and Running the Model in Go

In the attached code you can observe the whole processing operations split into main sections:

• Load the model

• Load an image

• Create input tensors (preprocess the image)

• Run the session (run inference)

• Fetch outputs (predictions)

• Find the best prediction and disply results

Our goal is to detect what’s on that image, we want to know if that’s a squirrel:

package main

import (
    "bufio"
    "fmt"
    "image"
    "image/jpeg"
    "log"
    "os"

    "github.com/nfnt/resize"
    tf "github.com/wamuir/graft/tensorflow"
)

func main() {
    // Load the SavedModel
    model, err := tf.LoadSavedModel("saved_mobilenet_v2", []string{"serve"}, nil)
    if err != nil {
        log.Fatal("LoadSavedModel", err)
    }
    defer func(Session *tf.Session) {
        if e := Session.Close(); e != nil {
            log.Fatal("Session.Close", e)
        }
    }(model.Session)

    // Load an image
    img, err := loadImage("images/1.jpg")
    if err != nil {
        log.Fatal("loadImage", err)
    }

    // Preprocess the image
    tensor, err := makeTensorFromImage(img)
    if err != nil {
        log.Fatal("makeTensorFromImage", err)
    }

    inputOp := model.Graph.Operation("serving_default_x")
    if inputOp == nil {
        log.Fatal("model.Graph.Operation: serving_default_x not found")
    }

    outputOp := model.Graph.Operation("StatefulPartitionedCall")
    if outputOp == nil {
        log.Fatal("model.Graph.Operation: StatefulPartitionedCall not found")
    }

    // Run inference
    outputs, err := model.Session.Run(
        map[tf.Output]*tf.Tensor{
            inputOp.Output(0): tensor,
        },
        []tf.Output{
            outputOp.Output(0),
        },
        nil,
    )
    if err != nil {
        log.Fatal("Session.Run", err)
    }

    // Predictions
    predictions := outputs[0].Value().([][]float32)

    // Find the top-1 prediction
    bestIdx := 0
    bestScore := float32(0.0)
    for i, p := range predictions[0] {
        if p > bestScore {
            bestIdx = i
            bestScore = p
        }
    }

    labels, err := loadLabels("ImageNetLabels.txt")
    if err != nil {
        log.Fatal("loadLabels", err)
    }

    fmt.Printf("Predicted label: %s (index: %d, confidence: %.4f)\n", labels[bestIdx], bestIdx, bestScore)
}

func loadImage(filename string) (image.Image, error) {
    file, err := os.Open(filename)
    if err != nil {
        return nil, fmt.Errorf("os.Open: %w", err)
    }
    defer func(file *os.File) {
        if e := file.Close(); e != nil {
            log.Fatal("file.Close", e)
        }
    }(file)

    img, err := jpeg.Decode(file)
    if err != nil {
        return nil, fmt.Errorf("jpeg.Decode: %w", err)
    }

    return img, nil
}

func makeTensorFromImage(img image.Image) (*tf.Tensor, error) {
    // Resize to 224x224
    resized := resize.Resize(224, 224, img, resize.Bilinear)

    // Create a 4D array to hold input
    bounds := resized.Bounds()
    batch := make([][][][]float32, 1) // batch size 1
    batch[0] = make([][][]float32, bounds.Dy())

    for y := bounds.Min.Y; y < bounds.Max.Y; y++ {
        row := make([][]float32, bounds.Dx())
        for x := bounds.Min.X; x < bounds.Max.X; x++ {
            r, g, b, _ := resized.At(x, y).RGBA()
            row[x] = []float32{
                float32(r) / 65535.0, // normalize to [0,1]
                float32(g) / 65535.0,
                float32(b) / 65535.0,
            }
        }
        batch[0][y] = row
    }

    return tf.NewTensor(batch)
}

func loadLabels(filename string) ([]string, error) {
    file, err := os.Open(filename)
    if err != nil {
        return nil, fmt.Errorf("os.Open: %w", err)
    }
    defer func(file *os.File) {
        if e := file.Close(); e != nil {
            log.Fatal("file.Close", e)
        }
    }(file)

    var labels []string

    scanner := bufio.NewScanner(file)
    for scanner.Scan() {
        labels = append(labels, scanner.Text())
    }

    if err = scanner.Err(); err != nil {
        return nil, fmt.Errorf("bufio.Scanner: %w", err)
    }

    return labels, nil
}

The output is as follows:

go run main.go
2025-04-27 18:56:20.238487: I tensorflow/cc/saved_model/reader.cc:83] Reading SavedModel from: saved_mobilenet_v2
2025-04-27 18:56:20.244913: I tensorflow/cc/saved_model/reader.cc:52] Reading meta graph with tags { serve }
2025-04-27 18:56:20.244945: I tensorflow/cc/saved_model/reader.cc:147] Reading SavedModel debug info (if present) from: saved_mobilenet_v2
WARNING: All log messages before absl::InitializeLog() is called are written to STDERR
I0000 00:00:1745772980.292412 2175877 mlir_graph_optimization_pass.cc:425] MLIR V1 optimization pass is not enabled
2025-04-27 18:56:20.298863: I tensorflow/cc/saved_model/loader.cc:236] Restoring SavedModel bundle.
2025-04-27 18:56:20.505321: I tensorflow/cc/saved_model/loader.cc:220] Running initialization op on SavedModel bundle at path: saved_mobilenet_v2
2025-04-27 18:56:20.562274: I tensorflow/cc/saved_model/loader.cc:471] SavedModel load for tags { serve }; Status: success: OK. Took 323789 microseconds.
Predicted label: fox squirrel (index: 336, confidence: 8.3710)

As you can see, the most common tag is a “fox squirrel”, which is exactly what we wanted to achieve. Personally not sure if this is a fox squirel or any other regular squirrel, but for sure it’s a squirrel.

All the resources like models, images and labels you can find in the article repository.

Common Pitfalls and Troubleshooting

Issues with the TensorFlow library:

go run main.go
# github.com/wamuir/graft/tensorflow
../../../go/pkg/mod/github.com/wamuir/graft@v0.10.0/tensorflow/tensor.go:69:26: could not determine what C.TF_FLOAT8_E4M3FN refers to
../../../go/pkg/mod/github.com/wamuir/graft@v0.10.0/tensorflow/tensor.go:68:26: could not determine what C.TF_FLOAT8_E5M2 refers to
../../../go/pkg/mod/github.com/wamuir/graft@v0.10.0/tensorflow/tensor.go:70:26: could not determine what C.TF_INT4 refers to
../../../go/pkg/mod/github.com/wamuir/graft@v0.10.0/tensorflow/tensor.go:71:26: could not determine what C.TF_UINT4 refers to

Even though TensorFlow is installed via Homebrew, it's not properly configured for pkg-config, which is needed for Go to find and link against the TensorFlow C library.

Run brew link --force libtensorflow

Then if needed add also env vars to you bash profile file (I’m using the .zshrc):

# TensorFlow configuration
export LIBRARY_PATH="/opt/homebrew/lib:$LIBRARY_PATH"
export CPATH="/opt/homebrew/include:$CPATH"
export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig:$PKG_CONFIG_PATH"

Sources

• Article Golang code repository: https://github.com/flashlabs/kiss-samples/tree/main/tensorflow

• Image classification model: https://www.kaggle.com/models/google/mobilenet-v2/tensorFlow2

• Sample images: https://www.kaggle.com/datasets/kkhandekar/object-detection-sample-images

• ImageNet labels: https://storage.googleapis.com/download.tensorflow.org/data/ImageNetLabels.txt

• TensorFlow: https://www.tensorflow.org/

Fuzzing is a type of automated testing which continuously manipulates inputs to a program to find bugs. Go fuzzing uses coverage guidance to intelligently walk through the code being fuzzed to find and report failures to the user. Since it can reach edge cases which humans often miss, fuzz testing can be particularly valuable for finding security exploits and vulnerabilities.

https://go.dev/doc/security/fuzz/

Mostly fuzzing is being used in parsers, formatters, decoders, network handlers and other security-critical code.

It helps to find:

• panics

• nil pointer dereferences

• memleaks

• unhandled errors

• unexpected behaviors

• security vulnerabilities (like buffer overflow or infinite loops)

But hey, what about the web API’s? The REST endpoints are full of user input handling and this is the perfect place for fuzzing!

The Handler

Let’s assume we have an endpoint responsible for a user creation. The input payload comes in the JSON format:

func CreateUserHandler(w http.ResponseWriter, r *http.Request) {
    var req struct {
        Username string `json:"username"`
        Age      int    `json:"age"`
    }

    err := json.NewDecoder(r.Body).Decode(&req)
    if err != nil {
        http.Error(w, "Invalid request", http.StatusBadRequest)

        return
    }

    if req.Age < 0 {
        http.Error(w, "Invalid age", http.StatusBadRequest)

        return
    }

    // Create user logic goes here.

    fmt.Fprintf(w, "User %s created successfully", req.Username)
}

The happy path is very simple, we decode the input payload into the struct, run some validation and register a user in the system.

As you can see there’s nothing special, but the JSON encoding part might get tricky. The JSON payload might be malformed, might cause unexpected results in further processing.

Would be nice to have something extra that will cover our handler with extra tests.

The Fuzz Test

The fuzz test in its basic form is an abstract layer over the regular *testing.T framework - we’re going to use the *testing.F input param.

There are couple of requirements for the fuzz test to work, like the name has to follow the pattern FuzzName, you can read more on it here.

Let’s focus on our basic fuzz test:

func FuzzCreateUserHandler(f *testing.F) {
    // Seed corpus with a valid JSON input
    f.Add(`{"username":"testuser","age":30}`)

    f.Fuzz(func(t *testing.T, body string) {
        req := httptest.NewRequest(http.MethodPost, "/users", strings.NewReader(body))
        req.Header.Set("Content-Type", "application/json")

        w := httptest.NewRecorder()

        CreateUserHandler(w, req)

        if w.Result().StatusCode == http.StatusInternalServerError {
            t.Errorf("Unexpected internal server error for input: %q", body)
        }
    })
}

What’s happening in our test:

• We’re feeding our seed corpus with some valid test cases

• Go’s fuzzer will mutate the input: remove/replace fields, add random bytes, change numbers, etc.

• We’re asserting that if the result’s StatusCode is http.StatusInternalServerError then the test should fail

The more sophisticated fuzz test, that will check for panic would be:

func FuzzCreateUserHandler(f *testing.F) {
    // Seed corpus with a valid JSON input
    f.Add(`{"username":"testuser","age":30}`)

    f.Fuzz(func(t *testing.T, body string) {
        defer func() {
            if r := recover(); r != nil {
                t.Fatalf("Handler panicked with input %q: %v", body, r)
            }
        }()

        req := httptest.NewRequest(http.MethodPost, "/users", strings.NewReader(body))
        req.Header.Set("Content-Type", "application/json")

        w := httptest.NewRecorder()

        CreateUserHandler(w, req)

        resp := w.Result()
        defer resp.Body.Close()

        if resp.StatusCode == http.StatusInternalServerError {
            t.Errorf("Unexpected 500 Internal Server Error for input: %q", body)
        }
    })
}

As you can see we’re using the recover() function that is checked at the end of the function call to see if there were any unexpected panics.

What you will assert is only up to you, the sky is the limit.

Run Fuzz Test

Okay, but how to run this test?

It’s simple, the regular tests you run go test ./… - the same way you can run the fuzz test btw (but limited to the regular execution - without fuzzing).

The fuzz test, you run:

go test -fuzz=Fuzz -fuzztime 10s

Please note the -fuzztime param. The fuzz tests can run really long, if you want to limit its execution time, this is the way.

The typical fuzz test output is similar to this:

go test -fuzz=Fuzz -fuzztime 10s
fuzz: elapsed: 0s, gathering baseline coverage: 0/411 completed
fuzz: elapsed: 0s, gathering baseline coverage: 411/411 completed, now fuzzing with 8 workers
fuzz: elapsed: 3s, execs: 244934 (81632/sec), new interesting: 0 (total: 411)
fuzz: elapsed: 6s, execs: 513074 (89363/sec), new interesting: 3 (total: 414)
fuzz: elapsed: 9s, execs: 785859 (90958/sec), new interesting: 4 (total: 415)
fuzz: elapsed: 10s, execs: 882683 (89005/sec), new interesting: 5 (total: 416)
PASS
ok      github.com/flashlabs/kiss-samples/fuzzing    10.445s

What does those sections even mean?

• gathering baseline coverage - before Go starts throwing random data at your code, it first runs your fuzz target with all the seeded inputs in your corpus.

• gathering baseline coverage: 0/411 completed - it means that Go has prepared a 411 inputs and run 0 out of it

• gathering baseline coverage: 411/411 completed - now it’s done. Go knows what your code coverage looks like before fuzzing

• now fuzzing with 8 workers - Go is launching 8 parallel processes in the background (8 goroutines) that will now work on our input, mutate it and feed it to our test function, looking for

  • crashes

  • panics

  • failed assertions

• new interesting: 3 (total: 414) - Go has found 3 new inputs that increase the code coverage, total corpus is now 414 (411 + 3)

  • keep in mind that since those input doesn’t trigger the t.Fatalf() or t.Errorf() and there’s no panic they’re considered safe and a run is considered a successfull one

The logic for the new inputs and the code coverage:

┌────────────────────────────────────────────┐
│  New input found                           │
└────────────────────────────────────────────┘
               │
               ▼
┌────────────────────────────┐
│ Does it increase coverage? │───► YES ──► Corpus grows
└────────────────────────────┘
               │
               ▼
            NO │
               ▼
     Input is discarded

Not every interesting input is a bug — fuzzers also collect inputs that increase code coverage. These inputs expand the test corpus, helping the fuzzer explore more paths over time.

Summary

While fuzzing is often associated with lower-level data parsing, it’s a powerful tool for web APIs too — especially since every API endpoint is essentially a parser of user-controlled input.

You need to experiment locally with different assertions and fuzzing times.

The full source code for this example with the http server you can find on the https://github.com/flashlabs/kiss-samples/tree/main/fuzzing

Sources

• https://go.dev/doc/tutorial/fuzz

• https://go.dev/doc/security/fuzz/

• https://github.com/flashlabs/kiss-samples/tree/main/fuzzing

Both concepts are strictly related to Scrum, although only one - the DoD - is defined by it.

The confusion in understanding the differences is related to the “Ready” and “Done” being similar in meaning.

To move further we need to introduce the third term: PBI - the Product Backlog Item, which is a set of business criteria to be developed.

The regular flow is that the PBI waits for its turn to be picked by the development team for the development. When it’s complete, it’s considered as done.

Knowing all of that, we can move forward.

Definition of Ready

The Definition of Ready is a set of criteria for the PBI to be picked by the developmnet team for the development.

The criteria are defined by the team and usually come down to:

• Who is the addressee of the PBI

• What does the owner wants to achieve

• Why this is needed

• And what are the Acceptance Criteria

Definition of Done

Usually the DoD is not just “the end of the development”, this should mean that the PBI is really DONE and is bringing a VALUE.

The typical DoD criteria might be as follows:

• The development is done

• The tests are covering business use cases

• The feature is being released

This is basically the end of life for the PBI.

Sources

• The Power of Jira Ticket: https://blog.skopow.ski/the-power-of-jira-ticket

• Scrum: https://www.scrum.org/

Incoming request payloads in JSON format often requires validation.

Validators might get complex and messy.

We don’t want our codebase to be messy - at least we try not to.

Solution

JSON schema

The best way is to convert our JSON representation of the incoming request into the JSON schema with the help of one of the multiple converters online. I was using the Free Online JSON to JSON Schema Converter.

From the input JSON payload:

{"id":"022eb326-6fa2-4932-8a5f-058a908616a4"}

We’re getting the JSON shema that looks like this for the mentioned input:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}

Schema validation

Now let’s get to the code.

The validation function:

// ValidateSchema validates payload against JSON schema located in the schema file.
func ValidateSchema(payload map[string]any, schema string) error {
    // Let's read the schema file
    file, err := os.ReadFile(schema)
    if err != nil {
        return fmt.Errorf("os.ReadFile: %w", err)
    }

    // Prepare validators for schema...
    schemaLoader := gojsonschema.NewStringLoader(string(file))
    // ... and payload.
    payloadLoader := gojsonschema.NewGoLoader(payload)

    // Validate schema against payload:
    result, err := gojsonschema.Validate(schemaLoader, payloadLoader)
    if err != nil {
        return fmt.Errorf("gojsonschema.Validate: %w", err)
    }

    // If there was something wrong, communicate the errors:
    if !result.Valid() {
        errMsg := "JSON validation failed:\n"
        for _, desc := range result.Errors() {
            errMsg += fmt.Sprintf("- %s\n", desc)
        }
        return fmt.Errorf("%w: %s", ErrInvalidPayload, errMsg)
    }

    return nil
}

Working application

Let’s put all the piecen together (file main.go):

package main

import (
    "encoding/json"
    "errors"
    "fmt"
    "log"
    "os"

    "github.com/google/uuid"
    "github.com/xeipuuv/gojsonschema"
)

var ErrInvalidPayload = errors.New("invalid payload")

type RequestPayload struct {
    ID uuid.UUID `json:"id"`
}

func main() {
    // Request payload.
    p, err := payload()
    if err != nil {
        log.Fatal(err)
    }

    // Validate incoming payload.
    if err = ValidateSchema(p, "schema/payload.json"); err != nil {
        log.Fatal(err)
    }

    // We're good!
    fmt.Println("Schema validated")
}

// ValidateSchema validates payload against JSON schema located in the schema file.
func ValidateSchema(payload map[string]any, schema string) error {
    // Let's read the schema file
    file, err := os.ReadFile(schema)
    if err != nil {
        return fmt.Errorf("os.ReadFile: %w", err)
    }

    // Prepare validators for schema...
    schemaLoader := gojsonschema.NewStringLoader(string(file))
    // ... and payload.
    payloadLoader := gojsonschema.NewGoLoader(payload)

    // Validate schema against payload:
    result, err := gojsonschema.Validate(schemaLoader, payloadLoader)
    if err != nil {
        return fmt.Errorf("gojsonschema.Validate: %w", err)
    }

    // If there was something wrong, communicate the errors:
    if !result.Valid() {
        errMsg := "JSON validation failed:\n"
        for _, desc := range result.Errors() {
            errMsg += fmt.Sprintf("- %s\n", desc)
        }
        return fmt.Errorf("%w: %s", ErrInvalidPayload, errMsg)
    }

    return nil
}

// payload returns sample request payload in map[string]any format.
func payload() (map[string]any, error) {
    r := &RequestPayload{ID: uuid.New()}

    payload, err := json.Marshal(r)
    if err != nil {
        return nil, fmt.Errorf("json.Marshal: %w", err)
    }

    var data map[string]any
    if err := json.Unmarshal(payload, &data); err != nil {
        return nil, fmt.Errorf("json.Unmarshal: %w", err)
    }

    return data, nil
}

➜  payloadschema git:(main) ✗ go run main.go
Schema validated

Sources

• Go code used in this article - Flashlabs’ KISS samples

• Free Online JSON to JSON Schema Converter

• UUID Generator

• You’re being afraid of making a production deployment because when something goes wrong it will be your fault?

• You’re feeling stressed before joining a meeting because you might get accused for a project/product/initiative failure?

• Someone can abuse you directly because of any work-related activity?

If your answer to any of the questions above is “yes”, then “congratulations”, you’re working in a Blame Culture environment that indicates your company’s failure.

What is Post Portem

The Post Mortem:

(…) is a process used to identify the causes of a (…) failure (…), and how to prevent them in the future. [1]

It’s that simple! This is a process where we can focus on what has gone wrong and why and this will lead us to the conclusion - how we can avoid similar situations in the future.

In most cases, Post Mortem analysis is a process based on a simple document format in which we provide:

• a short description of the event

• how it happened

• and what steps we intend to take in the future to prevent a similar situation.

Often, there is also a place in such a document to list the members of the team that the incident concerns. Important - we include members of the entire team working on the initiative, not the unit directly related to the incident. This is mainly done so that more details about the situation/incident can be obtained later. In the future, when similar challenges are taken on, these members will usually be more experienced and will know better how to effectively lead/support such initiatives.

Modern Software Development

In a Modern Software Development which often uses agile and lean methodologies that are focused on the outcome, iteration, product requirements and collaboration, there’s no place for the Blame Culture.

Good software is being created by the people who can trust and respect each other. All team members work for the success of the product. Everyone is working to the best of their ability and we must assume they are acting in good faith. No one introduces bugs intentionally and no one sabotages our product.

If something isn't working, if errors occur, it means we need to focus on improving our processes that allowed this to happen.

Keep your work environment clean - get rid of the Blame Culture!

Sources

• Blame in organizations - https://en.wikipedia.org/wiki/Blame_in_organizations [1]

• Postmortem documentation - https://en.wikipedia.org/wiki/Postmortem_documentation

Couple days ago Alex Albert from Anthropic announced that they’ve rolled out a PDF support directly in prompt’s message. Until now it was possible to upload a PDF documents only in the Claude’s interface, but wasn’t from the API’s PoV - you had to extract data manually and provide it in the prompt’s payload (the same way as the Anthropic was doing when accepting documents from the UI requests).

As always you can find a code snippets on how to manage this use case directly on the Anthropic website. Unfortunatelly there’re only examples for Shell, Python and TypeScript. If you’re using anthropic-sdk-go for Golang, there’s lack of such examples. That’s the reason for this article.

PDF in Go SDK

Install Anthropic SDK:

go get -u 'github.com/anthropics/anthropic-sdk-go@v0.2.0-alpha.4'

Initialize Anthropic client with the anthropic-beta header:

client := anthropic.NewClient(
    option.WithAPIKey("API_KEY"),
    option.WithHeader("anthropic-beta", "pdfs-2024-09-25"),
)

The API_KEY you can obtain in the Antrhopic Console.

Convert a PDF document into the base64 format string:

file, err := os.Open("./dogs.pdf")
if err != nil {
    panic(fmt.Errorf("failed to open file: %w", err))
}

fileBytes, err := io.ReadAll(file)
if err != nil {
    panic(err)
}

fileEncoded := base64.StdEncoding.EncodeToString(fileBytes)

Send a document altogether with a prompt via SDK:

message, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
    MaxTokens: anthropic.Int(1024),
    Messages: anthropic.F([]anthropic.BetaMessageParam{{
        Role: anthropic.F(anthropic.BetaMessageParamRoleUser),
        Content: anthropic.F(
            []anthropic.BetaContentBlockParamUnion{
                anthropic.BetaTextBlockParam{
                    Text: anthropic.F(content),
                    Type: anthropic.F(anthropic.BetaTextBlockParamTypeText),
                },
                anthropic.BetaBase64PDFBlockParam{
                    Source: anthropic.F(anthropic.BetaBase64PDFSourceParam{
                        Data:      anthropic.F(fileEncoded),
                        MediaType: anthropic.F[anthropic.BetaBase64PDFSourceMediaType](anthropic.BetaBase64PDFSourceMediaTypeApplicationPDF),
                        Type:      anthropic.F[anthropic.BetaBase64PDFSourceType]("base64"),
                    }),
                    Type: anthropic.F(anthropic.BetaBase64PDFBlockTypeDocument),
                },
            },
        ),
    }}),
    Model: anthropic.F(anthropic.ModelClaude3_5Sonnet20241022),
})

Be sure to use the model anthropic.ModelClaude3_5Sonnet20241022!

And that’s it!

Working example

Here’s the full working example:

package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "io"
    "os"

    "github.com/anthropics/anthropic-sdk-go"
    "github.com/anthropics/anthropic-sdk-go/option"
)

func main() {
    client := anthropic.NewClient(
        option.WithAPIKey("API_KEY"),
        option.WithHeader("anthropic-beta", "pdfs-2024-09-25"),
    )

    content := "How many dogs are in the attached document?"

    println("[user]: " + content)

    file, err := os.Open("./dogs.pdf")
    if err != nil {
        panic(fmt.Errorf("failed to open file: %w", err))
    }

    fileBytes, err := io.ReadAll(file)
    if err != nil {
        panic(err)
    }

    fileEncoded := base64.StdEncoding.EncodeToString(fileBytes)

    message, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
        MaxTokens: anthropic.Int(1024),
        Messages: anthropic.F([]anthropic.BetaMessageParam{{
            Role: anthropic.F(anthropic.BetaMessageParamRoleUser),
            Content: anthropic.F(
                []anthropic.BetaContentBlockParamUnion{
                    anthropic.BetaTextBlockParam{
                        Text: anthropic.F(content),
                        Type: anthropic.F(anthropic.BetaTextBlockParamTypeText),
                    },
                    anthropic.BetaBase64PDFBlockParam{
                        Source: anthropic.F(anthropic.BetaBase64PDFSourceParam{
                            Data:      anthropic.F(fileEncoded),
                            MediaType: anthropic.F[anthropic.BetaBase64PDFSourceMediaType](anthropic.BetaBase64PDFSourceMediaTypeApplicationPDF),
                            Type:      anthropic.F[anthropic.BetaBase64PDFSourceType]("base64"),
                        }),
                        Type: anthropic.F(anthropic.BetaBase64PDFBlockTypeDocument),
                    },
                },
            ),
        }}),
        Model: anthropic.F(anthropic.ModelClaude3_5Sonnet20241022),
    })
    if err != nil {
        panic(err)
    }

    println("[assistant]: " + message.Content[0].Text + message.StopSequence)
}

The output should looks like this:

➜  pdf2claude git:(main) ✗ go run main.go
[user]: How many dogs are in the attached document?
[assistant]: In this document, there are 5 dogs shown in black and white silhouette/portrait style. The breeds appear to be:

1. What appears to be a Jack Russell Terrier or similar mixed breed (top left)
2. An Australian Shepherd or similar long-haired herding dog (top right)
3. A French Bulldog (bottom left)
4. What looks like a Jack Russell Terrier or similar terrier breed (bottom middle)
5. A Chihuahua (bottom right)

The images are stylized in a high contrast black and white design, showing distinctive features of each breed.

The complete example you can find here on the GitHub.

Sources

• Twitter: https://x.com/alexalbert__/status/1852393994892042561

• Anthropic: https://docs.anthropic.com/en/docs/build-with-claude/pdf-support

• SDK: https://github.com/anthropics/anthropic-sdk-go

• Code: https://github.com/flashlabs/kiss-samples/tree/main/pdf2claude

• PDF document: https://www.templatesarea.com/free-dog-vector-illustrations-svg-png-pdf-design-diy/

Imagine having an interface called Runner that looks like this:

type Runner interface {
    Run() error
}

And a struct called Worker that you want to implement the mentioned interface. What you need to do? Ofc the only thing required is to add a Run function according to the interface:

type Worker struct {
}

func (w Worker) Run() error {
    return nil
}

Voilà! Now your Worker struct implements the Runner interface.

The whole program now looks like this:

package main

import "fmt"

type Runner interface {
    Run() error
}

type Worker struct {
}

func (w Worker) Run() error {
    return nil
}

func main() {
    w := Worker{}

    fmt.Println("worker", w)
}

You can run your program and everything is fine:

➜  interfaces git:(main) ✗ go run main.go
worker {}

Interface Mutation → Problem

Okay, but what will happen if you change the Runner interface?

type Runner interface {
    Run() error
    Stop() error
}

Well, you run the program and… nothing happens. Program runs successfully, but Worker is no longer compliant with the Runner interface, bc it’s missing the Stop function:

➜  interfaces git:(main) ✗ go run main.go
worker {}

Compile-time Compliance

How to be sure that your struct implements the interface at a complie-time? That’s easy! You just need to add this line:

var _ Runner = (*Worker)(nil)

What it does, you ask?

• The underscore _ is used only as a blank identifier, means to ignore the value.

• The Runner is the interface that we want to check.

• And the right side of the assignement is a type conversion of nil to a pointer of the Worker struct.

Thanks to this we enforce at the compile-time that the given type (Worker) implements the interface (Runner).

Having the main packages like this (with the missing Stop function in the Worker):

package main

import "fmt"

type Runner interface {
    Run() error
    Stop() error
}

var _ Runner = (*Worker)(nil)

type Worker struct {
}

func (w Worker) Run() error {
    return nil
}

func main() {
    w := Worker{}

    fmt.Println("worker", w)
}

When we try to run this program:

➜  interfaces git:(main) ✗ go run main.go
# command-line-arguments
./main.go:10:16: cannot use (*Worker)(nil) (value of type *Worker) as Runner value in variable declaration: *Worker does not implement Runner (missing method Stop)

We got a compile-time error.

Let’s fix this quickly by adding a missing Stop function:

func (w Worker) Stop() error {
    return nil
}

And we’re good:

➜  kiss-samples git:(main) ✗ go run main.go
worker {}

That’s it! Hope you like it and use it in your own projects!

Sources

• Code samples: https://github.com/flashlabs/kiss-samples/tree/main/interfaces

In general, the application profiling is the process of analyzing the behavior and performance of an app to identify its bottlenecks, inefficiencies, and areas for optimization. This usually involves collecting detailed information about various aspects of the application, such as:

• CPU and memory usage

• Execution time

• I/O operations

• Threading and concurrency

• Resource utilization

Types of collected data might differ between profilers and programming languages.

How to profile your app?

Step 1: Blank import the pprof package for the side effects - it will start collecting the profiling data

import (
    _ "net/http/pprof"
)

Step 2: Expose the pprof debug HTTP endpoint:

go func() {
    log.Println(http.ListenAndServe("localhost:6060", nil))
}()

And that’s it! You’re good to good! You can access now your profiler at the http://localhost:6060/debug/pprof/

Note: Please remember, that your program needs to be running in order to access the profiler at the mentioned link. If it’s terminating after you run it - it doesn’t have a worker nature, that is constantly running until you kill it, just add the following snippet at the end of your main function:

<-make(chan any)

// The same as:
// ch :=  make(chan any)
// <-ch

This will keep your program running. It creates an empty channel of any type and waits for a data to pull it from. Since no one is sending there anything, the program will keep waiting and running.

Your program already exposes an HTTP server? That’s not a problem! All you need to do is just blank import the pprof package. The pprof handlers will be automatically registered under the /debug/pprof/. Let’s say you have exposed an HTTP server at the port 8080, then your pprof debug session will be available at the http://localhost:8080/debug/pprof/.

You don’t have to also block the program termination in such case, because the HTTP server blocks the main goroutine, preventing the program from exiting.

To recap, the whole code looks like this:

package main

import (
    "log"
    "net/http"
    _ "net/http/pprof"
)

func main() {
    go func() {
        log.Println(http.ListenAndServe("localhost:6060", nil))
    }()

    // Your code goes here

    <-make(chan any)
}

What does the profiler says?

My profiler is exposed at the 6060 port, so visiting the URL http://localhost:6060/debug/pprof/ I see:

The profiler data are split into the following sections:

• allocs: A sampling of all past memory allocations

• block: Stack traces that led to blocking on synchronization primitives

• cmdline: The command line invocation of the current program

• goroutine: Stack traces of all current goroutines. Use debug=2 as a query parameter to export in the same format as an unrecovered panic.

• heap: A sampling of memory allocations of live objects. You can specify the gc GET parameter to run GC before taking the heap sample.

• mutex: Stack traces of holders of contended mutexes

• profile: CPU profile. You can specify the duration in the seconds GET parameter. After you get the profile file, use the go tool pprof command to investigate the profile.

• threadcreate: Stack traces that led to the creation of new OS threads

• trace: A trace of execution of the current program. You can specify the duration in the seconds GET parameter. After you get the trace file, use the go tool trace command to investigate the trace.

Feel free to explore the available sections to get to know your app better.

Visualizing profiler data

If you prefer the visual way of analyzing the data, the pprof tool comes for the rescue.

Step 1: Install the pprof tool:

go install github.com/google/pprof@latest

Step 2: Install the Graphviz to generate the graphic visualizations of profiles:

brew install graphviz

Make sure that the graphviz/bin directory is in your $PATH, otherwise the pprof won’t be able to generate visualizations.

Now, the full example on how to visualize the profile data with the pprof and the graphviz.

I have the following code in the worker package (directory):

package worker

import (
    "context"
    "log"
    "time"
)

const (
    interval = time.Second * 3
)

type worker struct {
}

func (w worker) run(ctx context.Context) {
    t := time.NewTicker(interval)
    defer t.Stop()

    for {
        select {
        case <-ctx.Done():
        // cleanup
        case <-t.C:
            log.Println("Worker cycle")
        }
    }
}

func Start(ctx context.Context) {
    log.Println("Starting worker")

    w := worker{}
    w.run(ctx)
}

And that’s how my main program looks like now:

package main

import (
    "context"
    "log"
    "net/http"
    _ "net/http/pprof"

    "github.com/flashlabs/tools/worker"
)

func main() {
    go func() {
        log.Println(http.ListenAndServe("localhost:6060", nil))
    }()

    ctx := context.Background()
    worker.Start(ctx)
}

Now I just start my program:

go run main.go
2024/09/22 13:29:06 Starting worker
2024/09/22 13:29:09 Worker cycle
2024/09/22 13:29:12 Worker cycle
2024/09/22 13:29:15 Worker cycle
...

And to visualize the goroutines:

Step 1: Download the goroutine profile and save it in the goroutine_profile.prof file

curl http://localhost:6060/debug/pprof/goroutine -o goroutine_profile.prof

Step 2: Run the pprof to analyze and visualize the data in saved file:

go tool pprof goroutine_profile.prof

Now you are in the the pprof interactive mode, you can f.e. display the functions and how many goroutines are in each state with the top command:

go tool pprof goroutine_profile.prof
File: main
Type: goroutine
Time: Sep 22, 2024 at 1:09pm (CEST)
Entering interactive mode (type "help" for commands, "o" for options)
(pprof) top
Showing nodes accounting for 5, 100% of 5 total
Showing top 10 nodes out of 36
      flat  flat%   sum%        cum   cum%
         4 80.00% 80.00%          4 80.00%  runtime.gopark
         1 20.00%   100%          1 20.00%  runtime.goroutineProfileWithLabels
         0     0%   100%          1 20.00%  bufio.(*Reader).Peek
         0     0%   100%          1 20.00%  bufio.(*Reader).fill
         0     0%   100%          1 20.00%  github.com/flashlabs/tools/worker.Start
         0     0%   100%          1 20.00%  github.com/flashlabs/tools/worker.worker.run
         0     0%   100%          1 20.00%  internal/poll.(*FD).Accept
         0     0%   100%          2 40.00%  internal/poll.(*FD).Read
         0     0%   100%          3 60.00%  internal/poll.(*pollDesc).wait
         0     0%   100%          3 60.00%  internal/poll.(*pollDesc).waitRead (inline)

To visualize the same data, just type the web in the pprof interactive mode:

(pprof) web

This will generate the visualized call graph of the goroutines and opens it in your browser immediately. The graph will looks like this:

For more information on how to read the visualization graphs and how to work with the pprof I strongly recommend to visit the pprof documentation page.

Sources

Pprof official page - https://github.com/google/pprof

Profiling Go Programs - https://go.dev/blog/pprof

Graphviz home page - https://www.graphviz.org/