Validating a container

Before you begin: Complete Building a Docker container. That topic assumes you have already completed Build a gRPC RTD service.

Once your container is built, you are ready to test it.

Test locally

This section covers what to implement and configure before testing: familiarizing yourself with ARTF, implementing GetMutations, handling response codes and circuit breakers, and configuring your metrics endpoint A URL which is configured to interact with a server in a specific way.. For the Index testing tool itself, see Using the Index testing tool.

Familiarize yourself with ARTF

The IAB Interactive Advertising Bureau (IAB). An advertising business organization that develops industry standards, conducts research, and provides legal support for the online advertising industry. Tech Lab has published an open-source implementation of ARTF at github.com/IABTechLab/agentic-rtb-framework. It contains Go and Rust reference implementations, sample test payloads in samples/, and a browser-based testing interface. You can use the ARTF testing tools locally without any involvement from Index to validate your implementation before requesting deployment. The Index testing tool, covered in Using the Index testing tool, is used for final validation against a live-like environment and requires Docker Hub access provisioned by your Index Representative.

Implement GetMutations

Before testing, confirm your container satisfies the contract it is being tested against. The RTBExtensionPoint service, the GetMutations RPC, and the port it listens on are all defined in the Service contract section of Build a gRPC RTD service. For what GetMutations receives and returns, and the recommended handler structure, see the What your container receives, What your container returns, and Implementation pattern sections of that same topic.

Handle response codes and circuit breakers

Return standard gRPC status codes. See the Response codes and Circuit breaker logic sections in Build a gRPC RTD service for the specific thresholds.

Configure your metrics endpoint

Expose an HTTP Prometheus metrics endpoint at /metrics on SERVER_PORT. The required metric is rpc.server.duration, a histogram with boundaries 0.001, 0.002, 0.003, 0.004, 0.005, 0.007, 0.010 in seconds. Permitted tags: rpc.system, rpc.grpc.status_code, rpc.method, rpc.service, error_type. Total cardinality must not exceed 10,000.

rpc.server.duration is required. Containers that do not expose this metric will fail Index Cloud health checks and will not receive traffic.

The following is an example of a correctly formatted /metrics response:

# HELP rpc_server_duration Measures the duration of inbound RPC.
# TYPE rpc_server_duration histogram
rpc_server_duration_sum{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type=""} 0.004
rpc_server_duration_count{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type=""} 1
rpc_server_duration_bucket{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type="",le="0.001"} 0
rpc_server_duration_bucket{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type="",le="0.002"} 0
rpc_server_duration_bucket{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type="",le="0.003"} 0
rpc_server_duration_bucket{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type="",le="0.004"} 1
rpc_server_duration_bucket{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type="",le="0.005"} 1
rpc_server_duration_bucket{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type="",le="0.007"} 1
rpc_server_duration_bucket{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type="",le="0.010"} 1
rpc_server_duration_bucket{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type="",le="+Inf"} 1

You can expose other metrics as required. Index will collect these metrics and make them available to you. Total metric cardinality should not exceed 10,000.

In addition to your own local testing, Index conducts functional testing on your API before it is deployed to production. If your container does not meet the specifications described in this documentation, it may not be deployed.

For the Index testing tool used to send test traffic to your container and validate it against a live-like environment, see Using the Index testing tool.