The merchant presses Compare and receives a message: something went wrong. Pressing again produces the same message. The app might lack permission, have rejected a file, encountered a supplier outage or completed the comparison without returning the result. The customer cannot choose a sensible next step because the software has hidden the state of the work.
Self-diagnostics should explain what the app attempted, what is known about the failure, what remains uncertain and which supported action can follow. They connect customer-facing clarity with operator evidence. A useful system helps ordinary users resolve routine conditions while giving support enough context for difficult ones, without exposing credentials or other customers’ records.
The title proposes a design habit rather than a claim that every application needs a complex diagnostic platform. A small file tool may need clear validation and an operation record. A durable multi-step service needs richer state and recovery evidence. Start with the failures that can block the customer’s promised result.
Describe the work as states the customer can understand
An operation can be received, validated, waiting, running, completed, failed or awaiting review. The exact states depend on the product, but their meanings should be explicit. A progress display that remains at eighty percent forever is less useful than a clear statement that the service is waiting for an external response.
For a hypothetical catalog comparison, separate file acceptance from valid comparison. The upload can succeed while the required supplier-cost column is missing. The comparison can complete while several rows remain unmatched. The report can be generated while notification delivery fails. Combining these conditions into one success or failure flag loses information.
Define the customer consequence of each state. A missing column prevents a valid comparison. An unmatched row needs review but may not invalidate the whole report. A failed notification does not necessarily mean the report is unavailable. Those distinctions prevent unnecessary retries and help the customer find the work already completed.
Use timestamps for meaningful events. Last successful comparison, last attempted connection and data freshness can change the decision. A healthy connection tested yesterday does not establish that today’s operation succeeded. Show what was checked rather than a timeless green badge.
Use an operation identifier to connect the evidence
A support request becomes easier to investigate when the user can share an operation identifier. The identifier links the customer-visible result to the relevant internal record. It should not serve as an unrestricted access token or reveal sensitive account details.
Record the intended task, creation time, supported input summary, relevant product version, state transitions and outcome. Keep the fields narrow enough to support diagnosis. A record of every raw input may be unnecessary and create risks beyond its value.
For the catalog example, an operator might need to know that a supported CSV import contained duplicate product identifiers and lacked a date field. They may not need the complete catalog in routine telemetry. If detailed records are necessary for a specific investigation, use an authorized access path with appropriate retention.
The identifier should survive retries when they belong to the same intended operation, while separate operations remain distinguishable. Otherwise a user pressing the button repeatedly can produce several disconnected stories that support cannot reconstruct. The idempotency chapter develops how operation identity also helps control repeated external effects.
Distinguish known causes from guesses
An error message should describe what the system established. A permission response can support a statement that access was denied. A timeout supports a statement that a response was not received within the allotted period. It does not necessarily establish that the external service is down or that the attempted write never occurred.
This distinction matters when actions affect another system. If a request to update a record times out, retrying without reconciliation can repeat an effect. The diagnostic should identify the uncertain outcome and direct the workflow to check the authoritative result before trying again where required.
For a read-only comparison, a timeout may allow a simpler retry. Even then, preserve the distinction between data unavailable and no discrepancy found. A system that labels a failed comparison clean gives false reassurance; one that labels missing data dangerous creates false urgency.
AI-generated explanations require the same evidence boundary. An assistant can summarize recorded state, but it should not invent a causal story to make the message feel helpful. Where several causes remain possible, show the known condition and the next test that can distinguish them.
Give the user a supported next step
A useful diagnostic connects the failure to an action. A missing field can link to a sample format. An expired authorization can lead to a clear reconnection process. A temporary limit can show when another attempt is appropriate. A suspected defect can provide the operation identifier and support route.
The action should match the user’s authority and knowledge. Asking a merchant to inspect server traces is usually inappropriate. Asking them to confirm which supplier file they intended to compare may be reasonable. Operator-only information can remain behind a separate access boundary.
Avoid a generic retry button for every condition. Retrying a malformed file repeats the same failure. Retrying an uncertain external write may create risk. A retry is useful when the condition is plausibly transient and the operation is designed for safe repetition.
If no safe user action exists, say what the service will do next and how the customer can get help. A message can be candid without becoming technical: the comparison could not be completed because the service lacks the required permission; reconnect the supported account or contact support with this operation identifier.
Choose telemetry for the question it answers
Telemetry is recorded information about system behavior. Different forms answer different questions. A metric can show how often comparisons fail. A log can record a particular validation outcome. A trace can follow a request through components and identify where progress stopped.
OpenTelemetry documents traces, metrics, logs and baggage as supported signal categories. Its page also identifies other categories as under development or proposal. Specific maturity and support vary by component, so implementation should check the actual language and exporter rather than applying one stability claim to the entire project. OpenTelemetry signals.
Start from the operational question. To know whether many customers face missing fields, count validation classes. To investigate a particular failed operation, retain state and correlation. To understand a slow external dependency, trace relevant stages. Collecting every available attribute can increase cost without improving these decisions.
Keep business outcome and technical health separate. Successful requests do not establish useful reports. A comparison can return normally while using stale data. Include checks tied to the customer promise, such as expected source date and supported row matching, alongside infrastructure measures.
Minimise sensitive diagnostic data
Diagnostic records can accidentally capture credentials, tokens, customer identities, supplier terms or personal information. The implementer needs to inspect what instrumentation emits rather than assume a library knows which fields are sensitive in the application’s context.
OpenTelemetry’s sensitive-data guidance emphasizes collecting information for an observability purpose and reviewing necessary attributes. It also warns that hashing predictable identifiers does not automatically provide adequate anonymization. These are implementation considerations, not a complete legal analysis for every deployment. OpenTelemetry sensitive-data guidance.
Define an allowed field set where practical. Operation state, error class, duration and product version may suffice for routine diagnosis. Avoid raw request bodies and authorization headers unless a narrowly justified investigation requires appropriately protected access. Scrubbing after collection can help, but preventing unnecessary collection reduces exposure earlier.
Separate customer-facing diagnostics from internal detail. A public status message should not display another account’s identifiers, internal service locations or a raw stack trace. A support export should contain the minimum relevant evidence and make its destination and purpose clear.
The privacy-design chapter examines broader data responsibilities. Diagnostic usefulness does not remove those obligations; it gives another reason to design the information boundary carefully.
Keep tenant boundaries in the diagnosis
In a service used by several customers, every diagnostic lookup needs the correct account context. An operation identifier alone should not let one user inspect another’s report. Support tools should enforce their own access controls and preserve a record of consequential investigation.
Test a denied lookup as well as a successful one. A valid operation identifier associated with another account should not return sensitive details. An expired or revoked role should not retain access merely because a browser still has an old link.
The same rule applies to AI support tools. A natural-language request should not bypass the account boundary. The tool that retrieves diagnostic records needs to validate access outside the model, using the actual user’s permitted scope. The agent-security chapter develops why persuasive instructions are insufficient as permission enforcement.
A useful support workflow can still be fast. Narrow account-scoped retrieval and a clear operation summary reduce the need for operators to browse broad data stores. Security and legibility can support one another when the evidence is organized around the authorized task.
Treat recovery as a separate operation
Diagnosis identifies a condition. Recovery changes something or repeats work. Keep the transition visible. A system should not escalate from explaining a failure to altering records without the required authority and checks.
For the hypothetical catalog app, recovery might mean uploading a corrected file or rerunning a read-only comparison. A later feature might prepare price updates. That action needs a preview, the appropriate approval and verification against the destination system. A report explaining a problem does not automatically authorize its correction.
Record what the recovery attempted and whether it succeeded. If a rollback is available, define its scope. Restoring an application version does not necessarily reverse data already written to an external platform. If only part of a multi-step action can be compensated, the diagnostic should preserve that partial state.
The rollback chapter examines these limits. Self-diagnostics should make recovery boundaries easier to inspect rather than hide them behind an optimistic message that everything has been fixed.
Test failures on purpose
A diagnostic feature needs evaluation against the conditions it promises to distinguish. Simulate missing fields, denied permissions, temporary dependency failure, stale data, duplicate requests and partial completion in an appropriate test environment. Label simulations as simulations; they do not establish live production reliability.
Define expected messages and allowed actions independently. A missing column should produce a clear format correction, not a generic outage warning. An uncertain write should direct reconciliation, not unconditional retry. A cross-account lookup should be denied without exposing the target record.
Include recovery tests. After a corrected input, can the customer obtain a valid result? After reconnection, is the operation state accurate? After a dependency returns, does waiting work resume appropriately? These tests concern behavior the customer relies on, not merely the existence of an error class in code.
Preserve a few difficult cases as protected evaluation examples. If every diagnostic test is rewritten to match the current implementation, the suite may confirm its own assumptions. The testing chapter explains why user-visible outcomes deserve independent checks.
Diagnostic health needs observation too
The diagnostic path can fail. Logs may stop exporting, identifiers may be missing or a status display may lag behind the authoritative operation record. A system that reports healthy because it receives no errors can mistake absent evidence for success.
Include checks on the evidence pipeline appropriate to the app. Can a known test operation be found? Are state transitions arriving? Is the customer view based on current records? Does the support export omit sensitive fields as intended? These questions keep observability from becoming a decorative dashboard.
Set retention according to the operational purpose and applicable requirements. Short-lived routine detail may be enough, while an unresolved incident needs a preserved investigation record. Longer retention creates storage and data-handling costs. Keep the policy explicit rather than treating diagnostic data as free material to collect indefinitely.
Account for sampling when interpreting absence. A trace system may retain only selected operations, while a business-state record should preserve the outcomes needed for customer continuity. If a trace cannot be found, support should know whether it was sampled out, expired or never emitted. Those explanations change the investigation. A diagnostic summary can state the available evidence without pretending to contain a complete history.
Also distinguish a local account failure from a broad incident. One customer’s revoked permission should not generate a global outage notice. A dependency failure affecting many accounts should not send every user through unnecessary reconnection. Compare the failure class and scope before deciding what to display. The customer needs enough information to choose a next step, while the operator needs enough aggregation to identify a shared cause. Keeping those views connected prevents a routine exception from being escalated into an incident and a real incident from being dismissed as individual error.
Review the most frequent unexplained states. If many operations end in an unknown category, the diagnostic model may be too coarse. Improve the classification where it changes the next action. Avoid creating dozens of categories whose differences no user or operator can use.
Count the operating benefit honestly
Self-diagnostics can reduce support effort, improve resolution and expose defects earlier, but those benefits need observation. The system also costs development time, storage and maintenance. It deserves an economic case tied to the failures it addresses.
An explicitly hypothetical improvement might reduce a repeated support investigation from twenty minutes to five. If the issue occurs twelve times monthly, the apparent time saving is three hours per month. The business should check actual cases, account for new work and confirm customers reach resolution rather than merely stop sending messages.
A rare consequential failure can justify diagnostics even when ticket volume is low. A broad speculative monitoring layer can remain unjustified when the product has only a simple supported operation. Match the investment to customer consequence, uncertainty and operating capacity.
What Would We Do at Salars?
For proposed Salars merchant apps, we would begin with an operation record and a small set of useful failure states. Supplier Margin Guard and Merchant Revenue Guard remain proposals; no diagnostic implementation or measured support reduction is established here.
A first catalog workflow would distinguish received file, invalid format, missing permission, waiting dependency, completed comparison, unmatched rows and unavailable result. The customer would see the condition and supported next step. The operator would receive a narrow account-scoped summary linked by operation identifier.
Telemetry would avoid unnecessary raw catalog and credential data. Tests would include clean results, stale inputs, partial completion, unsafe retries and denied cross-account access. Recovery that changes business records would use a separate reviewed action path.
The pilot ledger would measure whether customers can resolve routine failures and whether operators can investigate difficult ones with less effort. Those observations would support further investment only within their tested scope.
When something goes wrong, the software should leave the customer better informed about the work, not merely aware that the button failed. That is the first practical promise of self-diagnostics.
Explore the AI Software Factory series and the wider AI section.
Sources
- OpenTelemetry, Signals: forms of telemetry and stated category maturity.
- OpenTelemetry, Handling sensitive data: collection boundaries and identifier limitations.
Official passages checked October 7, 2026. Diagnostic workflows, evaluations and time savings are proposed or hypothetical. No live Salars reliability result is claimed.
Loading comments…