feat: add prometheus metrics support

[Niahh]

This PR introduces Prometheus-compatible metrics to the AMF to support observability and performance monitoring in Free5GC deployments.

Key Features

• SBI Metrics: Track inbound/outbound HTTP requests on the Service-Based Interface (SBI) with counters and latency histograms.
• NGAP/NAS Message Metrics: Export counters for each NGAP/NAS message type handled by the AMF.
• Business Metrics: Track the different amf specific operations/states, such as Handovers, PDU sessions, CM connection, gmm States, ...
• Built-in Metric Server: Exposes a /metrics HTTP endpoint that is configurable and compatible with Prometheus scraping.
• Modular Design: Metrics logic is isolated in a dedicated metrics package in the Util project to minimize code coupling and simplify reuse across NFs.
• No External Dependencies: Uses the official Prometheus Go client library only — no sidecars or exporters required.

Motivation

Introducing native metrics is a foundational step toward:

• Understanding real-time behavior of the AMF
• Coupled with testing tools such as PacketRusher, it can help with debugging some scenarios.
• Integrating Free5GC into production-grade observability stacks (e.g., Prometheus + Grafana)

Configuration

The metrics server is disabled by default. To enable, add the proper section :

# Metrics configuration
# If using the same bindingIPv4 as the sbi server, make sure that the ports are different
metrics:
	enable: true # (Optional, default false)
	scheme: http # (Required) the protocol for metrics (http or https, default https)
	bindingIPv4: 127.0.0.18 # (Required) IP used to bind the metrics endpoint (default 0.0.0.0)
	port: 9091 # (Optional, default 9091) port used to bind the service
	tls: # (Optional) the local path of TLS key (Could be the same as the sbi ones)
		pem: /home/sam/private-network/code/free5gc/cert/amf.pem # AMF TLS Certificate
		key: /home/sam/private-network/code/free5gc/cert/amf.key # AMF TLS Private key
	namespace: free5gc # (Optional, default free5gc)

Performance impact

Tests were made for NAS and NGAP message handling with metrics enabled and metrics disabled over 1000 iterations

NAS

16% Bytes Handled by operation Increased
9% Number of Allocation by operation

NGAP

6,6% Bytes Handled by operation Increased
3,4% Number of Allocation by operation

Backward Compatibility

100% backward compatible – metrics support is optional and deactivated until activated by the user.

Integration

The same metrics architecture is being adapted across other Free5GC NFs (AUSF, NRF, SMF , etc.) to ensure consistency and maintainability.

Pictures

Quick view of the metrics produced

This work is sponsored by Free Mobile!

[linouxis9]

Congratulations @Niahh for your first PRs to free5gc! :-)

[ianchen0119]

@Niahh @linouxis9

It's so nice to see those contributions!
We're currently collaborating with CNTi to demonstrate the best practice of the cloud-native 5GC.
I believe that your valuable contributions significantly help the community!

[Niahh]

FYI : Need to run a golangci on each commit + rebase to resolve conflict (working on that)

Edit: Done 😁

[ianchen0119]

Do we treat it as an error?
Or print a warning log and continue the initialization?

[Niahh]

I was assuming that if the metrics were enabled in the config, an error would be better than a warning. However it is a side functionality to the NF so we could just log a warning. Let me look in the code to see if no weird case would happen with the current metrics implementation if we just logs a warning 😄

[ianchen0119]

@Niahh
The PR free5gc/openapi#60 has been merged.
You can update the openapi package, then the golangci-lint should pass!

[Niahh]

I refactored with a link to the latest main branch, I´m awaiting a release of openapi to update it again.

Regarding the comment you made @ianchen0119 about logging a warning if the metrics server do not initialize properly, I decided to keep the error due to the fact that it is a opt-in configuration.

If the server had some trouble during the initialization, with only a warning the user could overlook it (there is a lot of logs at start up), and in an automation script it could lead to a misinterpretation that everything is as the user expect it to be in the config.

If not mandatory for the user and they don't want to fix the error, they can just disable the metrics in the configuration.

What do you think ?

[reki9185]

@ianchen0119 @Alonza0314 I think the rest of the parts look good to me.

[ianchen0119]

@Niahh

I just released the new openapi version: https://github.com/free5gc/openapi/releases
So you can update the dependency now.

I refactored with a link to the latest main branch, I´m awaiting a release of openapi to update it again.

Regarding the comment you made @ianchen0119 about logging a warning if the metrics server do not initialize properly, I decided to keep the error due to the fact that it is a opt-in configuration.

If the server had some trouble during the initialization, with only a warning the user could overlook it (there is a lot of logs at start up), and in an automation script it could lead to a misinterpretation that everything is as the user expect it to be in the config.

If not mandatory for the user and they don't want to fix the error, they can just disable the metrics in the configuration.

What do you think ?

It makes sense to me, I think the current implementation is good.

[Niahh]

Hello @ianchen0119, I have updated the PRs to point out directly to the new Openapi 1.2.1 release 🎉. It should now pass every pipelines, I will keep an eye if that is not the case 😁.